Audit log

Every meaningful action in your org is recorded. Queryable, filterable, and a foundation for compliance, support, and security investigations.

What gets logged

• Token issuance. Every authorization_code exchange (when enabled via webhook), every client_credentials token, every device-flow token approval.
• Consent — consent.granted and .revoked.
• Org membership — invites, role changes, removals.
• OIDC clients — oidcClient.created, .updated, .deleted, .secret.rotated.
• BYO provider configs — socialProvider.upserted, .enabled, .disabled.
• Webhook subscriptions — webhook.created, .updated, .deleted, .test.
• Token gates — tokenGate.created, .updated, .deleted.
• Brands and apps — every mutation.

The full event vocabulary lives in Webhook events (the audit log writes fire synchronously alongside the webhook events).

Each entry

interface AuditLogEntry {
  id: string
  org: string                      // owning org id
  actorUserId?: string             // null for system actions
  action: string                   // e.g. 'oidcClient.created'
  resourceType: string             // e.g. 'oidcClient'
  resourceId: string
  metadata?: Record<string, unknown>
  timestamp: string                // ISO 8601
}

actorUserId is null for things Synq does on its own (e.g. token.issued is the system minting a token after the user authenticated; the actorUserId is the user only for explicit mutations like oidcClient.created).

The metadata blob carries context relevant to the event:

{
  "action": "oidcClient.created",
  "metadata": {
    "appName": "Marketplace Web",
    "type": "web",
    "redirectUris": ["https://marketplace.com/api/oauth/callback"]
  }
}

For events that mutate, the metadata may include before and after snapshots.

Querying

GET /identity/organizations/<orgSlug>/audit-log
  ?action=oidcClient.created
  &actorUserId=user_abc
  &since=2026-06-01T00:00:00Z
  &until=2026-06-04T00:00:00Z
  &limit=100
Authorization: Bearer <token with IdentityOrgPermission.MembersView>

Response:

{
  "items": [
    {
      "id": "log_abc",
      "org": "org_xyz",
      "actorUserId": "user_abc",
      "action": "oidcClient.created",
      "resourceType": "oidcClient",
      "resourceId": "client_123",
      "metadata": { "appName": "Marketplace Web" },
      "timestamp": "2026-06-03T15:23:45Z"
    }
  ],
  "total": 1
}

Available filters:

total is the count matching the filter (not just the current page), so you can paginate accurately.

Retention

Audit log entries are retained per the org’s billing tier:

Records older than the tier limit are pruned by a daily job; deletion is permanent. For longer retention, subscribe to webhooks (which fire synchronously with the audit log writes) and ship to your own log store (S3, Datadog, Splunk, whatever).

Common queries

Who created this app?

GET /identity/organizations/acme/audit-log
  ?action=oidcClient.created
  &resourceId=client_abc

Who has been signing in as the deployment bot?

GET /identity/organizations/acme/audit-log
  ?action=token.issued
  &resourceId=client_bot

(Requires token.issued to be enabled — it’s off by default since it’s high-volume.)

Show all role changes for a specific user this week

GET /identity/organizations/acme/audit-log
  ?action=member.role.changed
  &resourceId=user_xyz
  &since=2026-05-28T00:00:00Z

CSV / JSONL export

The dashboard offers CSV and JSONL exports for the same query parameters. The API returns JSON; if you want CSV from the API, you can map it client-side.

Best practices

• Subscribe to webhooks for everything you care about. Audit log retention is bounded; webhooks let you keep an indefinite record.
• Index your own log store by Synq-Delivery. Deduped, append- only, queryable by your existing tools.
• Don’t poll the audit log endpoint as a real-time feed. Use webhooks for real-time. The audit log is for retrospective queries.
• Use metadata filters in queries instead of fetching everything and filtering client-side. Server-side filtering keeps your pagination meaningful.

Mental model summary

• The audit log records meaningful actions, with actor, action, resource, and metadata.
• Filter by any combination of action, actor, resource, and time range.
• Retention is bounded by tier; for long-term records, ship via webhooks to your own store.
• Don’t use it as a real-time feed; that’s what webhooks are for.