Audit trail

The audit trail is an append-only record of every privileged action performed in your Gateway organization. Use it for compliance reviews, incident investigation, and to answer “who changed this?” questions about routing policies, API keys, members, security settings, and more.

What gets audited

Mutations to org-scoped resources emit an audit event. Read-only API calls and inference traffic (request logs are a separate surface) are not audited.

Call GET /api/audit-trail/event-types/ to fetch the complete list at runtime.

Fields captured on each entry

Each audit row stores a denormalized snapshot of the actor and target so the entry stays interpretable even if the user, role, or organization is later deleted.

The table is append-only - there is no updated_at column and entries are never modified after they’re written.

Handling of sensitive fields

The audit trail is designed so that secret values (API keys, credential secrets, SSO client secrets, passwords) never reach an audit row in the first place:

• Auth-adjacent handlers omit the body. Credential, SSO, auth, password reset, and API key handlers pass request_body=None when emitting their audit event. The event records that the action happened (with the entity name in the description) but never persists the request payload.
• UPDATE handlers diff before mutating. A field-level diff (compute_changes) runs against the pre-mutation instance and the validated request body. Fields that contain secret values are summarized as "changed" rather than rendering 'old' to 'new', so the rendered description in the audit row contains no secret material.
• Body truncation in descriptions. Each diffed value is truncated to 100 characters in event_description, so long blobs (e.g., raw JSON config) don’t bloat the audit row even when they’re not sensitive.

What an UPDATE entry looks like

UPDATE events combine an identifying prefix with a per-field diff. The description shape is:

Updated <entity> <name> with ID <id>. Changed <field>: 'old' to 'new', <field>: 'old' to 'new'

List-valued fields render as added/removed sets:

Updated project Production with ID proj_abc. Changed allowed_models: added gpt-5.2; removed gpt-4o

This makes it possible to scan the audit feed and immediately see what changed in any update, without having to fetch the resource history separately.

Viewing the audit trail in the dashboard

Open Settings → Audit trail in the Merge Gateway dashboard. The page shows a paginated, filterable table of events with:

• A free-text filter by user
• Event-type dropdown (sourced from GET /api/audit-trail/event-types/)
• Date-range picker
• CSV export button (the export itself is recorded as an AUDIT_LOG_EXPORTED event so you have a trail of who pulled what)

Querying via the API

Two control-plane endpoints expose the audit trail:

Query parameters supported by the list and export endpoints:

Response shape (list):

1
{
2
  "items": [
3
    {
4
      "id": "8c5e0c2e-...-...",
5
      "created_at": "2026-05-13T15:04:11Z",
6
      "user_name": "Alice Example",
7
      "user_email": "[email protected]",
8
      "role_name": "Admin",
9
      "organization_id": "...",
10
      "organization_name": "Acme",
11
      "ip_address": "203.0.113.42",
12
      "url": "/organizations/.../blocklist-rules",
13
      "method": "POST",
14
      "event_type": "BLOCKLIST_RULE_CREATED",
15
      "event_description": "Created blocklist rule (block) - customers=[customer_abc], providers=[anthropic]"
16
    }
17
  ],
18
  "total": 1842
19
}

The CSV export contains: Timestamp, User Name, User Email, Role, IP Address, Event Type, Event Description. Cells starting with =, +, -, @, \t, or \r are prefixed with a single quote to neutralize CSV injection.

Required permission

Listing and exporting the audit trail requires the view_audit_trail permission on the caller’s role. The built-in Admin and Read Only roles include this permission; Developer does not. See Roles and permissions for the full permission matrix.

Retention

Audit entries are append-only and persist indefinitely on the org. There is no automatic TTL or archival - once written, an event is permanent. If you need to surface long-windowed compliance reports, the API supports arbitrary date ranges.

FAQ

Next steps