Export Audit Logs for Compliance and Reporting

Every action taken in the Idem Ledger — whether by a human operator or an automated agent — is recorded in an immutable audit log. The compliance export endpoint lets you stream those records as newline-delimited JSON (NDJSON) for any time window you specify, making it straightforward to feed audit data into your SIEM, data warehouse, or compliance reporting pipeline.

Export audit log

Send a GET request to /api/v1/compliance/audit-export with the required from and to query parameters. The response is a streaming NDJSON body: one JSON object per line, one line per audit record.

curl "https://api.your-domain.com/api/v1/compliance/audit-export?from=2024-01-01T00:00:00Z&to=2024-02-01T00:00:00Z&type=ALL" \
  -H "Authorization: Bearer $IDEM_API_KEY"

Query parameters

Parameter	Required	Description
`from`	✅ Yes	Start of the export window. Must be a valid ISO-8601 timestamp (e.g., `2024-01-01T00:00:00Z`).
`to`	✅ Yes	End of the export window. Must be a valid ISO-8601 timestamp and must be after `from`.
`type`	No	Filter by actor type. Accepted values: `HUMAN`, `AGENT`, or `ALL`. Defaults to `ALL` when omitted.

Use type=HUMAN to export only records generated by human operators (console or direct API key usage), and type=AGENT to isolate automated agent activity. This is especially useful when your compliance team needs to audit human approvals separately from programmatic operations.

NDJSON format

The response body is a stream of newline-delimited JSON. Each line is a self-contained JSON object representing one audit record. There is no wrapping array — process the stream line by line. A single audit record looks like this:

{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"HUMAN","action":"POST_TRANSACTION","actorKeyId":"key_operator_01","occurredAt":"2024-01-15T10:30:00Z","payload":{}}

Key fields in each record:

Field	Description
`id`	Unique identifier for this audit record.
`type`	Whether the action was taken by a `HUMAN` or `AGENT`.
`action`	The specific operation performed (e.g., `POST_TRANSACTION`, `REGISTER_SETTLEMENT`).
`actorKeyId`	The identifier of the API key that performed the action.
`occurredAt`	ISO-8601 timestamp of when the action occurred.
`payload`	Additional structured context about the action, such as the transaction ID or affected account.

Processing NDJSON

Because each line is independent JSON, you can pipe the response directly into jq to filter or transform records on the fly:

# Stream all HUMAN actions and extract just the action name and timestamp
curl -s "https://api.your-domain.com/api/v1/compliance/audit-export?from=2024-01-01T00:00:00Z&to=2024-02-01T00:00:00Z&type=HUMAN" \
  -H "Authorization: Bearer $IDEM_API_KEY" \
  | jq -c '{action: .action, occurredAt: .occurredAt, actor: .actorKeyId}'

To write the raw stream to a file for offline processing:

curl -s "https://api.your-domain.com/api/v1/compliance/audit-export?from=2024-01-01T00:00:00Z&to=2024-02-01T00:00:00Z" \
  -H "Authorization: Bearer $IDEM_API_KEY" \
  > audit-jan-2024.ndjson

Required scope

Your API key must have the COMPLIANCE_EXPORT scope to call this endpoint. Requests from keys without this scope receive a 403 Forbidden response. This scope should be granted only to keys used by compliance systems or authorized administrators, not to general-purpose service accounts.

For tenants with high transaction volumes, requesting large time windows in a single export can produce very large response streams. As a best practice, export in shorter windows — daily or weekly — rather than requesting months of data in one call. This keeps response sizes manageable, reduces the risk of a network interruption mid-stream, and makes it easier to parallelize ingestion into your downstream systems.

Get Started

Core Concepts

Guides

Export Audit Logs for Compliance and Reporting

Export audit log

Query parameters

NDJSON format

Processing NDJSON

Required scope

​Export audit log

​Query parameters

​NDJSON format

​Processing NDJSON

​Required scope

Export audit log

Query parameters

NDJSON format

Processing NDJSON

Required scope