Concepts

Concepts: Audit log

The audit log is the immutable record of every write that touches a tenant. The console's /audit page renders it for operators with acaso_os:admin.

What gets recorded

Every privileged endpoint that mutates state records one row in audit_log.

Field	Description
`id`	UUID, monotonically newer.
`created_at`	Timestamp with timezone.
`tenant_id`	The tenant the action belongs to.
`actor_key_id`	The session key id under which the action ran.
`actor_user_id`	The bound user resolved from the session's parent.
`action`	Dotted action name (`user.create`, `role.update`, `chat.archive`, etc.).
`resource`	The resource type acted on.
`subject_id`	The id of the affected row.
`pii_touched`	True when the action accessed PII fields.
`request_id`	Correlation id matching the `X-Request-Id` header.
`metadata`	JSON diff of before/after where relevant.

How the console reads it

GET/v1/admin/tenants/{slug}/audit-log

curl -X GET "https://your-acaso.example.com/v1/admin/tenants/{slug}/audit-log" \
  -H "Authorization: Bearer $ACASO_SESSION_TOKEN"

The endpoint returns a paginated cursor-based stream, newest first. The console renders columns for timestamp, actor (key id + resolved user display name), action, resource, and request_id.

Clicking a row opens the right-side detail sheet with the full payload — the JSON metadata (collapsible) and the request_id ready to copy for support tickets.

Filtering

The filter bar uses nuqs to mirror state into the URL. Sharing the URL with another operator reconstructs the exact view. Available filters:

Date range (from, to).
Action prefix (user.*, role.*, graphium.statement.*).
Actor user id.
pii_touched = true toggle.

When to use it

Self-check. "Did I really archive that chat?" Filter by your user id and action_prefix = chat.
Compliance request. "Show me everything that touched user U's PII in the last 90 days." Filter by pii_touched = true and subject_id = U.
Debugging a 403. Grab the X-Request-Id from the failed response and search the audit log.

Warning: The audit log is append-only. Rows cannot be edited or deleted through the API. Retention is governed by the tenant's compliance posture; talk to the platform team before changing it.

What gets recorded

Every privileged endpoint that mutates state records one row in audit_log.

Field

Description

id

UUID, monotonically newer.

created_at

Timestamp with timezone.

tenant_id

The tenant the action belongs to.

actor_key_id

The session key id under which the action ran.

actor_user_id

The bound user resolved from the session's parent.

action

Dotted action name (user.create, role.update, chat.archive, etc.).

resource

The resource type acted on.

subject_id

The id of the affected row.

pii_touched

True when the action accessed PII fields.

request_id

Correlation id matching the X-Request-Id header.

metadata

JSON diff of before/after where relevant.

How the console reads it

GET/v1/admin/tenants/{slug}/audit-log

curl -X GET "https://your-acaso.example.com/v1/admin/tenants/{slug}/audit-log" \
  -H "Authorization: Bearer $ACASO_SESSION_TOKEN"

The endpoint returns a paginated cursor-based stream, newest first. The console renders columns for timestamp, actor (key id + resolved user display name), action, resource, and request_id.

Clicking a row opens the right-side detail sheet with the full payload — the JSON metadata (collapsible) and the request_id ready to copy for support tickets.

When to use it

Self-check. "Did I really archive that chat?" Filter by your user id and action_prefix = chat.

Compliance request. "Show me everything that touched user U's PII in the last 90 days." Filter by pii_touched = true and subject_id = U.

Debugging a 403. Grab the X-Request-Id from the failed response and search the audit log.

Warning: The audit log is append-only. Rows cannot be edited or deleted through the API. Retention is governed by the tenant's compliance posture; talk to the platform team before changing it.