🧪 Beta — Available today; the interface contract may still change.
Audit and compliance reporting
By the end of this guide you will be able to:
- Trace from any business log line back to "who approved this in the first place"
- Fold agent authorization and access into your existing compliance reporting
- Answer the three questions auditors ask most, on the spot
Prerequisites
- Your resource services already log
sub,act.agent_idandaudit_idin business logs (how: Protect your APIs) — this is what makes the chain complete - You understand how the two IDs divide the work (see Audit and accountability chain)
Three ways to query
Forward: from an authorization to what followed
Given an audit_id or grant_id, see what happened after that authorization — issuance, exchange, access, recall, expiry. Use it to review "how was this authorization actually used".
Backward: from a business log to the authorization
Given a suspicious business operation (your log carries the audit_id), trace back to the original authorization: who approved it, what scope, when, and whether it is still valid.
This is the path incident response uses most, and the entire reason the resource side must log audit_id — without it, the chain stops at your API boundary.
By subject: everything one person or one agent did
- Query by
sub: which agents this user has authorized, and with what scope - Query by
act.agent_id: whose behalf this agent has acted on
Use it for periodic review and offboarding handovers — the person leaves, the agents they authorized keep running is the most common governance gap there is.
What a compliance report needs
Frameworks word it differently, but the elements overlap heavily. Assemble these five and most audit scenarios are covered:
| Element | Where it comes from |
|---|---|
| Agent inventory (what exists, who is accountable) | Registration records and accountable persons (see Register and manage your agents) |
| Authorization records (who approved what, and for how long) | Grant events by grant_id |
| Access records (what was actually done) | Your business logs plus sub / act from the token |
| Evidence of least privilege (requested vs actually granted) | grantedScopes compared against the requested scope |
| Recall records (revocation, disablement, expiry) | Terminal events on the audit chain (see Revocation and incident response) |
Reporting period and retention
Configure retention, access permissions and export formats for audit data according to your industry's requirements. We recommend covering at least your longest audit cycle — and logging the export operations themselves.
The three questions auditors ask
Q: Who approved this agent going live? Should it still exist? A: The inventory holds the registration record, the Owner and Sponsor, and the approval record. "Should it still exist" is a decision the Sponsor makes during review — which is exactly why a Sponsor is mandatory.
Q: Which customer data did it access last quarter, and in whose name? A: Query by act.agent_id for everything that agent did; each record carries sub (on whose behalf) and audit_id (under which authorization). The business detail lives in your logs, the authorization basis lives in the audit chain, and audit_id joins the two.
Q: If it goes wrong, how fast can you stop it? A: Answer by layer, not with a single vague number — stopping new authorizations is immediate; tokens already issued are governed by their lifetime, and your policy is to grant only minutes for task-level work. Full detail: Revocation and incident response. On this question honesty beats polish: claim more than you can do and a POC will test it on the spot.
FAQ
Can audit data be exported to our own SIEM? Audit events can be pulled through the API and shipped into your log platform. Use audit_id as the join key against your business logs — one search then shows both the authorization basis and the business consequence.
Can users see what they have authorized? We recommend a "my authorizations" page in your application: list that user's currently active authorizations (agent, scope, expiry) with a revoke entry point. The data comes from a query by sub.
Will agent activity get mixed up with human activity? No — as long as act from the token is recorded, "the user acted" and "an agent acted for the user" stay distinguishable. That is the value of the dual-subject design (see Token and claim reference).
Next steps
- Audit and accountability chain — the structure and fields of the chain.
- Protect your APIs: resource-side integration — wiring the chain into your business logs.
- Revocation and incident response — what to do once you know the scope.