How audit logging works
Every call totheauth.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
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.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.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.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.Filtering
All filter fields are optional and combinable. Results are ordered newest first unless you passorder: '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.
Only entries whose
code is one of these, for example ['hook_denied', 'hook_timeout', 'hook_error'] to list every hook block.Only entries with one of these events.
Exact resource, or a prefix when the value ends with
* (for example mcp:github:*). % and _ in the value are literal.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
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
EU AI Act, Article 12. Record keeping
EU AI Act, Article 12. Record keeping
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.
NIST AI RMF. GOVERN 1.7 / MANAGE 4.2
NIST AI RMF. GOVERN 1.7 / MANAGE 4.2
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. CC6.1 through CC7.2
SOC 2. CC6.1 through CC7.2
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, Annex A.8. Documentation of AI system behaviour
ISO 42001, Annex A.8. Documentation of AI system behaviour
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 userNext 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.