Auth Events

Immutable audit log of all authentication events. Auth: Authorization: Bearer <jwt> (admin scope required).

Endpoints

GET /api/auth/events

List auth events. Query: org_uuid?, user_uuid?, type?, from?, to? (ISO), limit? (max 500), offset?, outcome? (success|failure).

Output: ~~~json { "data": [{ "event_id": "evt-uuid", "type": "login.password", "outcome": "success", "user_uuid": "user-uuid", "org_uuid": "org-uuid", "ip_address": "1.2.3.4", "user_agent": "...", "metadata": {}, "created_at": "2026-05-11T10:00:00Z" }], "total": 1200 } ~~~

GET /api/auth/events/:event_id

Get single event with full metadata.

GET /api/admin/organizations/:org_uuid/auth-events

Org-scoped alias. Same response shape, pre-filtered to org.

GET /api/organizations/:org_uuid/audit-events/export

Export audit events as CSV or JSON. Query: format? (csv|json), from?, to?.

POST /api/admin/organizations/:org_uuid/auth-events/purge

Purge auth events older than the retention window. Admin-only. Returns { "purged": 1500 }.

Endpoint Summary

| Method | Path | Purpose | |---|---|---| | GET | /api/auth/events | List auth events (global) | | GET | /api/auth/events/{event_id} | Get single event | | GET | /api/organizations/{org}/audit-events | List org audit events | | GET | /api/organizations/{org}/audit-events/export | Export events | | GET | /api/admin/organizations/{org}/auth-events | List org auth events (admin) | | POST | /api/admin/organizations/{org}/auth-events/purge | Purge old events |

Event Types

login.password, login.magic_link, login.oidc, login.saml, login.totp_verify, login.recovery_code, session.revoked, session.bulk_revoked, token.refreshed, mfa.enrolled, mfa.disabled, step_up.challenged, step_up.verified, step_up.failed, svid.issued, svid.revoked, key.rotated

Retention

90 days by default; extend to 365 days via POST /api/operator/config (enterprise).

SDK Examples

Python

~~~python

List audit events

events = client.list_audit_events("org-uuid")

Export events

export = client.export_audit_events("org-uuid")

Admin: list auth events

auth_events = client.list_auth_events_admin("org-uuid")

Admin: purge old events

client.purge_auth_events("org-uuid") ~~~

Node.js / TypeScript

~~~typescript // List audit events const events = await client.listAuditEvents('org-uuid');

// Admin: list auth events const authEvents = await client.listAuthEvents('org-uuid'); ~~~

Go

~~~go // List audit events events, err := client.ListAuditEvents(ctx, "org-uuid") ~~~

Rust

~~~rust // List audit events let events = client.list_audit_events("org-uuid").await?;

// Export events let export = client.export_audit_events("org-uuid").await?;

// Admin: list auth events let auth_events = client.list_auth_events("org-uuid").await?;

// Admin: purge old events client.purge_auth_events("org-uuid").await?; ~~~

Error Reference

| Status | Code | Meaning | |---|---|---| | 400 | invalid_type | Unknown event type filter value | | 400 | invalid_date_range | from or to is not valid ISO 8601 | | 403 | forbidden | Admin scope required | | 404 | not_found | Event, org, or user not found | | 429 | rate_limited | Max 60 audit queries/min |