PPactDocs
Administration

Audit log

Pact's append-only audit log — filter and search every state-changing event, export to CSV/JSONL/XLSX, and subscribe to alerts when specific events fire.

Audit log

The audit log is Pact's system-of-record: every state-changing event in the platform appends a row to the domain_events table. The read API (api/routes/audit_log.py) is tenant-scoped — every query carries tenant_id, so cross-tenant reads return zero rows — and requires the admin module.

Query the log

code
GET /v1/audit-log?action_prefix=auth.&limit=50

Filters compose freely:

  • actor — filter by the acting user's ID
  • action (exact) or action_prefix (e.g. auth. for all auth events)
  • entity_type (aggregate type, e.g. Contact, Sequence) and entity_id (substring on the aggregate ID)
  • q — full-text search across actor, event type, aggregate type/ID, and the payload JSON (tsvector on Postgres, LIKE on SQLite)
  • success — true excludes failure events (those ending in .failed, .failure, .denied, .error, .blocked); false returns only failures
  • from / to — an occurred_at time range
  • sort — asc or desc (newest first by default)

Pagination uses an opaque (occurred_at, id) keyset cursor (pass back next_cursor), so page reads stay O(limit) no matter how deep you scroll or how fast new rows arrive. Responses carry an ETag fingerprint of the filtered set, so clients can poll cheaply with If-None-Match and get a 304 when nothing changed.

Filter helpers

Two endpoints back the filter combobox in the console:

code
GET /v1/audit-log/actors    — distinct actors
GET /v1/audit-log/actions   — distinct event types

Export

code
GET /v1/audit-log/export?format=csv

Exports the full filtered set as CSV, JSONL, or XLSX, capped at 100,000 rows — comfortably a full quarter for the largest tenants. Larger pulls should paginate through the list endpoint.

Watch subscriptions ("alert me when this fires")

Subscribe to a saved filter and get emailed when matching events arrive (api/routes/audit_watch.py):

code
POST /v1/audit-log/watch
{ "name": "Break-glass grants",
  "email": "[email protected]",
  "filters": { "action_prefix": "auth.sso.break_glass" } }

filters uses the same keys as the list query. A daily cron (08:00 UTC) evaluates every active subscription against events since its last_checked_at and notifies the owner on a match. Up to 20 subscriptions per tenant; list with GET and remove with DELETE /v1/audit-log/watch/{id}.

Append-only, read-only

The audit log is written by the platform, never by this API — there are no create, update, or delete routes for events. That is what makes it trustworthy as a compliance record. Retention (how many months of audit rows survive) is governed by retention_audit_months under PATCH /v1/admin/settings.

Security settingsSet audit retention windows.View asImpersonation actions are logged here.SSOSSO changes land under auth.sso.*.SessionsSession revocations are audited.