Skip to main content

How audit logging works

Every call to theauth.authorize() or theauth.authorizeByToken() writes an entry to the audit log, regardless of outcome. Allowed and denied calls are both recorded (the rate_limited value exists in the type, but the built-in permission engine records rate limit denials as denied). A call blocked by a beforeAuthorize hook, including a hook timeout or error, is logged as a denial in the agent’s hash chain (see Lifecycle hooks). A call for a revoked or expired agent is logged too. theauth.delegation.revoke() writes a chained delegation.revoke row for each link it revokes, cascaded links included, on the delegate’s chain (resource is delegation:<id>; parameters holds delegationId, fromAgent, toAgent, revokedBy when known, cascade, cascadeFrom and rootDelegationId). Revoking a link that is already revoked writes nothing. Calls for an unknown agent id or an unknown token have no agent row to attach to and are not logged. The SDK never updates entries; theauth.audit.cleanup({ retentionDays }) deletes entries older than the cutoff. authorize() returns an auditId linking the decision to its log entry:

Querying logs

AuditEntry type

string
Unique entry identifier (a UUID). Equal to the auditId returned by authorize().
string
The agent that triggered the authorization check.
string
The user who owns the agent.
string
The domain verb: the action the agent attempted (e.g. read, write, delete), or the tool name. Delegation rows written by 2.0 use delegate; rows written before that keep delegation.create and delegation.revoke, because action is hashed.
AuditEvent | null
What happened, from the event vocabulary. null on rows from writers that do not set it and on old rows the backfill could not classify. Not part of the audit hash.
string
The resource the action was attempted on.
Record<string, unknown>
Arguments passed to the tool at the time of the call.
'allowed' | 'denied' | 'rate_limited' | 'escalated'
The outcome of the check. The built-in permission engine writes allowed or denied. policy.evaluate() writes escalated when the action needs human approval. Rows also carry accountability fields such as the acting agent, the accountable human and the policy version; see Tamper-evident audit trail.
string
Free-text explanation of a denial. Absent on allowed entries.
DecisionCode
Machine-readable outcome, such as allowed, no_permission, rate_limited, hook_denied, hook_timeout or hook_error. Read from the nullable decision_code column, so it is undefined on rows written before that column existed. It is an index convenience, not evidence: it is not part of the audit hash, so use reason and the hashed fields when proving what happened.
number
Time taken to evaluate the decision, in milliseconds.
number
Optional token usage. The built-in permission engine does not populate it.
Date
When the authorization check occurred.

Filtering

All filter fields are optional and combinable. Results are ordered newest first unless you pass order: 'asc'. The timestamp column has 1 second resolution, so ordering uses the recorded_at_ms write-order column (strictly increasing per agent chain), then id to break ties. Rows written in the same second always come back in write order. recorded_at_ms is not part of the audit hash. Without filters or a limit, the query returns every entry.
string
Filter to a specific agent.
string
Filter to all agents owned by a user.
Date
Include entries on or after this timestamp.
Date
Include entries on or before this timestamp.
DecisionCode[]
Only entries whose code is one of these, for example ['hook_denied', 'hook_timeout', 'hook_error'] to list every hook block.
string[]
Filter to specific action names. Applied in the query, before limit.
AuditEvent[]
Only entries with one of these events.
string
Exact resource, or a prefix when the value ends with * (for example mcp:github:*). % and _ in the value are literal.
'asc' | 'desc'
desc (default) is newest first, asc is oldest first.
string
Opaque cursor from nextCursor of the previous page. Use it with audit.page().
'allowed' | 'denied' | 'rate_limited'
Filter by outcome.
number
Maximum entries to return. No default: all matching entries are returned when omitted.
number
Deprecated, use cursor. Offsets skip or repeat rows when entries are written between pages. Ignored when cursor is set.

Pagination

theauth.audit.page(filter) returns { entries, nextCursor }. Pass nextCursor back as cursor (with the same filter and order) to get the next page. It is null on the last page, and always null when you pass no limit. The cursor encodes the recorded_at_ms and id of the last row, so pages have no gaps or repeats even when rows share a millisecond or new rows arrive between requests.
audit.query() still returns a plain array. Over HTTP, GET /audit returns the same array by default. Add paged=true (or send cursor) to get { entries, nextCursor }; an invalid cursor answers 400. The query string accepts order, cursor, events (comma separated) and resource besides the existing filters. The query_audit MCP tool passes them through and always returns nextCursor.

Event vocabulary

event says what happened. action keeps the domain verb. For an authorization row, action is the requested action (read) and event is authorize. authorize.token, mcp.tool.call, agent.create and agent.revoke are reserved names that the built-in writers do not use yet. The list is open: a custom writer can pass any string as event to recordAuditEvent. Rows from before the event column read back with a backfilled value where the old action made it clear, otherwise null.

Exporting logs

The CSV export includes a header row (id,agentId,userId,action,resource,result,reason,durationMs,tokensCost,timestamp). Each row is one authorization decision. The parameters field appears only in the JSON export. The export returns a string, not a file.
Both since and until are optional on exports. Exports are capped at the 10,000 most recent matching entries, so page through audit.query if you need more.

Compliance references

Article 12 requires high-risk AI systems to log events automatically throughout the system lifecycle, including the period of activity and data used. theAuth records every authorization decision with agent identity, resource, action, parameters, outcome, and timestamp.
The NIST AI Risk Management Framework calls for documented accountability mechanisms and the ability to trace AI actions to specific identities. The audit trail links every decision to a named agent and user.
SOC 2 trust services criteria for logical access controls and system monitoring require evidence that access is granted only to authorized identities and that access events are logged. The allowed/denied result field is evidence that maps to CC6.1 to CC6.3, and the log of every decision maps to CC7.2. theAuth does not make you compliant on its own, and tamper-evidence needs protections at the database level.
ISO 42001 recommends documenting the behavior of AI systems in production. Exporting the audit log as JSON or CSV gives auditors a machine-readable record of every decision the system made.

Usage patterns

Monthly access report for a user
Agents with repeated denials today
High-frequency agent detection
A sudden spike in call volume from a single agent often indicates a runaway loop. Use theauth.agent.revoke() to cut off the agent while you investigate (revocation is permanent, so create a new agent afterwards).

Next steps

Compliance

Map audit data to EU AI Act, NIST, SOC 2, and ISO 42001.

REST API

Query audit logs via HTTP endpoints.

Admin dashboard

Visual audit log viewer with filters and export.
Last modified on October 18, 2026