Admin audit log viewer

GET

/admin/audit

• Local development behind nginx (port 8088 by default)

Cursor-paginated read of the system-wide audit event log. Every filter is optional; combining them narrows the result. Returns the rows ordered newest-first along with the total count (cursor-independent) so the UI can render a “X events matched” header and a next-page button.

next_cursor is an opaque base64-url token wrapping the last row’s (occurred_at, id) pair. Pass it back as the cursor query param to fetch the next page. Null when the response is the final page.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Query Parameters

event_type

string

actor_user_ref

integer format: int64

subject_user_ref

integer format: int64

since

string format: date-time

ISO-8601 lower bound on occurred_at (inclusive).

until

string format: date-time

ISO-8601 upper bound on occurred_at (inclusive).

limit

integer

default: 100 >= 1 <= 500

cursor

string

Responses

200

Page of audit events + total count.

object

items

required

Array<object>

One row from audit_events. metadata is the typed JSONB blob whose shape varies per event_type — see app/internal/audit/events.go for the per-type schemas. The UI renders well-known event types as structured changesets (“active → disabled”, etc.) and falls back to JSON dump for the rest.

object

id

required

string format: uuid

event_type

required

string

occurred_at

required

string format: date-time

subject_user_ref

integer format: int64

nullable

actor_user_ref

integer format: int64

nullable

ip

Actor IP address — PERSONAL DATA, and returned only to callers holding system.audit.pii.read on top of system.audit.read (#425).

Absent from the response entirely for callers without that capability, rather than blanked, so an empty value always means “no IP recorded” and never “you may not see it”. Consumers must already tolerate absence: the field has always been optional and nullable, since not every event carries an address.

string

nullable

user_agent

string

nullable

metadata

required

Typed per event_type — see audit/events.go.

object

key

additional properties

any

total

required

Total rows matching the filter (cursor-independent).

integer format: int64

next_cursor

string

nullable

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed