Audit Logs
Record your own customers' audit events, define schemas, filter, export to CSV, stream them, and let IT admins see their organization's events.
Audit Logs is an audit trail you offer to your customers. Your app sends the events (who did what to which object), OhAuthCat stores them per organization, and both you and the customer’s IT admins can read and export them. This is separate from OhAuthCat’s own audit log of your account.
Send an event
Section titled “Send an event”POST / (scope audit_log_events:write; reads need audit_log_events:read) with the organization_id and an event:
| Field | Meaning |
|---|---|
action |
Your action name, such as invoice.paid |
occurred_at |
When it happened |
actor |
Who did it (type, id, optional name and metadata) |
targets |
What it affected |
context |
Where it came from, such as the location and user agent |
metadata |
Any other details |
version |
The schema version to validate against (optional) |
Send an Idempotency-Key header: a retried request with the same key for the same organization records the event once. From the CLI: ohauthcat audit-logs emit --data-file event..
Schemas
Section titled “Schemas”Register a versioned schema per action with POST /: the target types and JSON Schemas for actor, target and event metadata (a bounded subset of JSON Schema). Events naming a version are validated against it; an unknown one answers audit_log_schema_not_found.
Read, export and stream
Section titled “Read, export and stream”GET /filters by organization, action, actor, target and time window (v1/ audit_log_events frominclusive,toexclusive).GET /returns the same selection as CSV, up to 10,000 rows. Cells that a spreadsheet would read as formulas are escaped.v1/ audit_log_events/ export GET /returns the selection as JSON events withv1/ audit_log_events/ export? format=json has_moreandnext_before; passnext_beforeasbeforeto export the next rows. From the CLI:ohauthcat audit-logs export --format json.- Log streaming can forward audit events (source
audit_log_event) to your SIEM, and an organization can stream its own events to its destination.
For IT admins
Section titled “For IT admins”The hosted setup portal has an audit log view: IT admins of an organization list and export their own organization’s events. Send them there with a portal link using the audit_logs intent.
Retention
Section titled “Retention”| Plan | Retention |
|---|---|
| Free | 7 days |
| Pro | 90 days |
| Business | 1 year |
| Enterprise | 1 year, or as agreed |