Appearance
Fresh 2026
Audit trail
How Merge Gateway records privileged actions in the per-org audit trail. Covers the catalog of audited events, fields captured on each entry (actor, role, IP, request body), how UPDATE events render field-level diffs, sensitive-field handling, dashboard + API access, and the permission required to view audit data.
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, and security settings.
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.
| Resource | Events |
|---|---|
| API keys | API_KEY_CREATED, API_KEY_DELETED |
| Credentials (BYOK) | CREDENTIAL_CREATED, CREDENTIAL_UPDATED, CREDENTIAL_DELETED |
| Members | MEMBER_INVITED, MEMBER_JOINED, MEMBER_ROLE_CHANGED, MEMBER_REMOVED, MEMBER_INVITATION_RESENT, MEMBER_INVITATION_REVOKED |
| Roles | ROLE_CREATED, ROLE_UPDATED, ROLE_DELETED |
| Auth | LOGIN_SUCCESS, LOGIN_FAILED, LOGOUT, PASSWORD_RESET |
| Org settings | ORG_SETTINGS_UPDATED |
| Routing policies | ROUTING_POLICY_CREATED, ROUTING_POLICY_UPDATED, ROUTING_POLICY_DELETED |
| Routing rules | ROUTING_RULE_CREATED, ROUTING_RULE_UPDATED, ROUTING_RULE_DELETED |
| Unified routing | UNIFIED_ROUTING_CONFIG_CREATED, UNIFIED_ROUTING_CONFIG_UPDATED, UNIFIED_ROUTING_CONFIG_DELETED, UNIFIED_ROUTING_CONFIG_REORDERED |
| Projects | PROJECT_CREATED, PROJECT_UPDATED, PROJECT_DELETED |
| SSO | SSO_PROVIDER_CREATED, SSO_PROVIDER_UPDATED, SSO_PROVIDER_DELETED, SSO_LOGIN_REQUIRED_ON, SSO_LOGIN_REQUIRED_OFF |
| Billing | PAYMENT_METHOD_CREATED, PAYMENT_METHOD_UPDATED, PAYMENT_METHOD_DELETED, BILLING_SETTINGS_UPDATED, CREDITS_PURCHASED |
| Blocklist | BLOCKLIST_RULE_CREATED, BLOCKLIST_RULE_UPDATED, BLOCKLIST_RULE_DELETED |
| Compression | COMPRESSION_SETTING_CREATED, COMPRESSION_SETTING_UPDATED, COMPRESSION_SETTING_DELETED |
| DLP | DLP_RULE_CREATED, DLP_RULE_UPDATED, DLP_RULE_DELETED |
| Evals | EVAL_SUITE_CREATED, EVAL_SUITE_UPDATED, EVAL_SUITE_DELETED, EVAL_CASE_CREATED, EVAL_CASE_UPDATED, EVAL_CASE_DELETED, EVAL_RUN_CANCELLED |
| Audit trail | AUDIT_LOG_EXPORTED |
The complete catalog is also surfaced in the event-type dropdown in the dashboard.
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.
| Field | Description |
|---|---|
created_at | Timestamp the event was recorded (UTC, with timezone) |
user_id | UUID of the user who performed the action, or null for system-driven events |
user_name / user_email | Denormalized at write time. Survive user deletion. |
role_name | The user's role at the moment of the event. Survives role rename or deletion. |
organization_id / organization_name | Denormalized. Survive org deletion. |
ip_address | Sourced from the CF-Connecting-IP header (Cloudflare) when present; otherwise the request socket IP |
url | HTTP request path |
method | HTTP method (POST, PATCH, DELETE, PUT) |
request_body | JSONB. For non-auth-adjacent handlers, the validated request body is stored as-is. For auth-adjacent handlers (credentials, SSO, auth, password reset, API keys), this field is null by design. See below. |
event_type | One of the values from the catalog above |
event_description | Human-readable summary (verb + entity + identifier, plus a change summary on UPDATE events) |
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=Nonewhen 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.
Non-auth-adjacent UPDATE handlers persist the validated request body to request_body as-is. Treat that column as containing the raw payload, and review your audit feed if you handle especially sensitive non-auth data.
What an UPDATE entry looks like
UPDATE events combine an identifying prefix with a per-field diff. The description shape is:
Updated with ID . Changed : 'old' to 'new', : '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-4oThis 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 covering every value in the catalog above
- Date-range picker
- CSV export button (the export itself is recorded as an
AUDIT_LOG_EXPORTEDevent so you have a trail of who pulled what)
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. All four built-in roles (Admin, Developer, Security, Read Only) include this permission. 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. The dashboard supports arbitrary date ranges if you need to pull long-windowed compliance reports.
FAQ
No. Inference traffic flows through a separate request-log surface (and the Security alerts feed). The audit trail covers administrative mutations only, such as settings changes, role assignments, and key creation.
Use the CSV export from the dashboard and forward it to your SIEM. There is no native webhook stream today.
Entries are denormalized at write time, so user_name, user_email, role_name, organization_name remain populated on the row even after the referenced entity is deleted. The FK columns (user_id, organization_id) are set to null via ON DELETE SET NULL.
No. The table is append-only and write-time only. Events are emitted during the mutation that triggers them and cannot be inserted retroactively.
Failed logins emit LOGIN_FAILED. Most other failed mutations do not write an audit entry because the mutation never began. The audit row commits in the same transaction as the mutation. Check your application logs for failures that didn't make it past authorization.
Next steps
Configure who can perform audited actions and who can view the audit trail
Blocklist mutations are audited end-to-end
PI configuration changes emit ORG_SETTINGS_UPDATED audit events