Fetch security/audit timeline

GET/tenants/{tenant_id}/security/audit

Returns the chronological security and governance audit event timeline for a tenant. Events include login attempts, permission changes, impersonation events, session revocations, policy updates, and identity config changes. Use for SOC 2 evidence gathering or investigating security incidents.

Request

Path parameters

Name	Type	Required	Description
tenant_id	string	Yes	The tenant identifier.

Query parameters

Name	Type	Required	Description
from	string (date-time)	No	Start of the event range (ISO 8601 datetime, inclusive).
to	string (date-time)	No	End of the event range (ISO 8601 datetime, inclusive).
event_type	string	No	Filter to a specific event type (e.g. "impersonation_started", "session_revoke_all").
limit	integer	No	Maximum number of events to return. Default: 50 · Maximum: 500

Responses

200 Tenant security audit timeline

Content type application/json, array of object · SecurityAuditEventV1.

Field	Type	Required	Description
id	integer	No
event_type	string	No	Machine-readable event type (e.g. "impersonation_started", "session_revoke_all", "policy_updated").
tenant_id	string	No
actor_id	integer, nullable	No	ID of the admin or system actor who triggered the event.
outcome	string	No	Result of the action that generated the event. One of: "success", "failure", "blocked"
metadata	object	No	Additional event-specific context (e.g. session ID, policy keys changed, IP address).
occurred_at	string (date-time)	No

Example

[
  {
    "id": 881,
    "event_type": "impersonation_terminated",
    "tenant_id": "acme",
    "actor_id": 3,
    "outcome": "success",
    "metadata": {
      "session_id": "imp_01HXN8K2V3PABC",
      "reason": "Issue resolved."
    },
    "occurred_at": "2026-04-08T10:47:00Z"
  }
]

404 Tenant not found

Example request

Paths are relative to the control-plane API base URL ($BASE_URL below).

curl -X GET "$BASE_URL/tenants/{tenant_id}/security/audit" \
  -H "Accept: application/json"