Audit Logs API

VeilForms automatically logs important actions in your account. Use the Audit Logs API to retrieve these logs for compliance reporting, debugging, or security monitoring.

List Audit Logs

Query Parameters:

ParameterTypeRequiredDescription
limitintegerNoMax entries to return (default: 50, max: 100)
offsetintegerNoStarting position for pagination (default: 0)
eventstringNoFilter by event type or category
formIdstringNoFilter logs for a specific form

Example Request:

curl "https://veilforms.com/api/audit-logs?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "logs": [
    {
      "id": "audit_1705312200_abc123",
      "userId": "user_xyz789",
      "event": "form.created",
      "details": {
        "formId": "vf_abc123",
        "formName": "Contact Form"
      },
      "meta": {
        "ip": "192.168.1.1",
        "userAgent": "Mozilla/5.0...",
        "region": "US"
      },
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "id": "audit_1705311000_def456",
      "userId": "user_xyz789",
      "event": "submission.received",
      "details": {
        "formId": "vf_abc123",
        "submissionId": "sub_def456",
        "encrypted": true
      },
      "meta": {
        "ip": "10.0.0.1",
        "userAgent": "VeilForms SDK/1.0",
        "region": "GB"
      },
      "timestamp": "2024-01-15T10:10:00Z"
    }
  ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Filter by Event Type

Example - Filter by exact event:

curl "https://veilforms.com/api/audit-logs?event=form.created" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example - Filter by category:

# Get all form-related events
curl "https://veilforms.com/api/audit-logs?event=form" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Form-Specific Logs

Example Request:

curl "https://veilforms.com/api/audit-logs?formId=vf_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "logs": [
    {
      "id": "audit_1705312200_abc123",
      "userId": "user_xyz789",
      "event": "form.updated",
      "details": {
        "formId": "vf_abc123",
        "changes": {
          "name": "Updated Contact Form",
          "webhookUrl": "https://example.com/webhook"
        }
      },
      "meta": {
        "ip": "192.168.1.1",
        "userAgent": "Mozilla/5.0..."
      },
      "timestamp": "2024-01-15T14:30:00Z"
    },
    {
      "id": "audit_1705312100_xyz789",
      "userId": "user_xyz789",
      "event": "form.created",
      "details": {
        "formId": "vf_abc123",
        "formName": "Contact Form"
      },
      "meta": {
        "ip": "192.168.1.1"
      },
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 2
}

Event Types

Form Events

EventDescription
form.createdA new form was created
form.updatedForm settings were modified
form.deletedA form was deleted
form.keys_regeneratedEncryption keys were rotated

Submission Events

EventDescription
submission.receivedA new submission was received
submission.deletedA single submission was deleted
submissions.bulk_deletedMultiple submissions were deleted (retention policy)

Authentication Events

EventDescription
user.registeredNew user registration
user.loginSuccessful login
user.login_failedFailed login attempt
user.password_resetPassword was reset
user.email_verifiedEmail address was verified

API Key Events

EventDescription
api_key.createdNew API key was created
api_key.revokedAPI key was revoked
api_key.usedAPI key was used for authentication

Settings Events

EventDescription
settings.updatedAccount settings were updated
branding.updatedBranding settings were changed
retention.updatedData retention settings were modified

Audit Log Entry Structure

{
  "id": "audit_1705312200_abc123",
  "userId": "user_xyz789",
  "event": "form.created",
  "details": {
    "formId": "vf_abc123",
    "formName": "Contact Form",
    "...": "event-specific fields"
  },
  "meta": {
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "region": "US",
    "origin": "https://yourdomain.com"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
FieldDescription
idUnique identifier for the log entry
userIdUser who performed the action
eventEvent type (see Event Types above)
detailsEvent-specific information
meta.ipIP address of the request
meta.userAgentBrowser/client user agent (truncated to 200 chars)
meta.regionGeographic region (country code)
meta.originOrigin of the request
timestampISO 8601 timestamp

Retention

Audit logs are retained for:

PlanRetention Period
Free30 days
Starter90 days
Pro1 year
EnterpriseCustom

A maximum of 1,000 entries are stored per user.

Error Responses

401 Unauthorized

{
  "error": "Invalid or missing authentication"
}

404 Not Found

{
  "error": "Form not found or access denied"
}

Returned when requesting logs for a form you don’t own.

405 Method Not Allowed

{
  "error": "Method not allowed"
}

Only GET requests are supported.

429 Too Many Requests

{
  "error": "Too many requests. Please try again later.",
  "retryAfter": 60
}

Rate limit: 30 requests per minute.

Example: Export Logs for Compliance

async function exportAuditLogs(startDate, endDate) {
  const logs = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await fetch(
      `https://veilforms.com/api/audit-logs?limit=${limit}&offset=${offset}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_JWT_TOKEN'
        }
      }
    );

    const data = await response.json();

    // Filter by date range
    const filtered = data.logs.filter(log => {
      const ts = new Date(log.timestamp);
      return ts >= startDate && ts <= endDate;
    });

    logs.push(...filtered);

    if (data.logs.length < limit) break;
    offset += limit;
  }

  return logs;
}

// Export last 30 days
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
const logs = await exportAuditLogs(thirtyDaysAgo, new Date());
console.log(`Exported ${logs.length} audit logs`);

Use Cases

Security Monitoring

Monitor for suspicious activity:

  • Failed login attempts (user.login_failed)
  • New API key creation (api_key.created)
  • Unexpected form deletions (form.deleted)

Compliance Reporting

Generate audit reports for:

  • GDPR data access requests
  • SOC 2 compliance
  • Internal security audits

Debugging

Trace issues by reviewing:

  • Recent form configuration changes
  • Submission delivery problems
  • API key authentication issues

Next Steps