# Audit Logs

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](/reference/api/management/).

## Send an event

`POST /v1/audit_log_events` (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.json`.

## Schemas

Register a versioned schema per action with `POST /v1/audit_log_schemas`: 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`](/errors/audit_log_schema_not_found/).

## Read, export and stream

- `GET /v1/audit_log_events` filters by organization, action, actor, target and time window (`from` inclusive, `to` exclusive).
- `GET /v1/audit_log_events/export` returns the same selection as CSV, up to 10,000 rows. Cells that a spreadsheet would read as formulas are escaped.
- `GET /v1/audit_log_events/export?format=json` returns the selection as JSON events with `has_more` and `next_before`; pass `next_before` as `before` to export the next rows. From the CLI: `ohauthcat audit-logs export --format json`.
- [Log streaming](/events/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

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

| Plan       | Retention            |
| ---------- | -------------------- |
| Free       | 7 days               |
| Pro        | 90 days              |
| Business   | 1 year               |
| Enterprise | 1 year, or as agreed |
