Operator - Audit

Overview

Audit events help answer who or what acted, which subject and connector were involved, and what outcome was recorded. The operator endpoints only read those events, while governed data-control requests may export or delete eligible audit rows.

Events are correlation anchors

subject_type and subject_id identify the affected resource; user, service_agent, and connector identify participants. trace_id joins execution history, while metadata carries the authorization snapshot or operation details.

Audit is not observability search

Use audit for accountable decisions and state-changing actions. Use traces, alerts, and failure groups for runtime diagnosis, then pivot back to audit when you need the actor and policy outcome.

Metadata is not automatically secret-safe

Gateway authorization metadata can contain the submitted payload, and the JSON view returns metadata directly. Callers must sanitize before submission; readers should handle audit output as potentially sensitive.

How it works

1. Narrow the timeline

   List recent events and narrow by filter[event_type] or filter[subject_type]. Results are paged newest first (limit defaults to 50, maximum 200); pass next_cursor back as cursor to read older events. Open the event detail and use its actor, connector, subject, and trace identifiers before drawing conclusions from a compact row.

2. Follow the identifiers

   Correlate trace_id with a trace and subject_id with the referenced resource. Treat absent actor fields as meaningful: some system processes have no user, while human actions should identify the session user.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

const response = await fetch("/api/v1/operator/audit_events?filter%5Bsubject_type%5D=authorization_check", {
  credentials: "same-origin",
  headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);

Troubleshooting

An event is missing

Verify the selected workspace and remove filters one at a time. A valid ID from another workspace returns 404, and an authorized data-deletion request may have removed eligible audit events when include_audit_logs was true.

Metadata contains sensitive content

The audit reader returns stored metadata directly and cannot retroactively make an unsafe submitted payload safe. Restrict access, remediate the submitting integration, and use governed deletion only under the workspace's data-handling policy.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.