Audit Logs

An audit log is the canonical record of what Alter did and why. Credential retrievals, policy decisions, grant lifecycle events, provider calls, and administrative actions are written with the available identity and correlation context needed for compliance and forensic review.

Audit logging is always enabled; there is no disable flag. Credential-touching backend paths require an explicit success, failure, denial, or error audit terminal. Direct SDK provider calls queue their audit report after the provider response. Audit-write failures are isolated from the primary operation and emit critical diagnostics and failure metrics rather than replacing the operation’s result.

What’s recorded

For every app.request():

• Caller identity — the API key, agent identity, and caller attribution.
• Principal identity — the user, group, system, or agent the grant belongs to.
• Grant — the grant_id, provider, and grant kind.
• Request — method, URL, response status, latency, and available size metadata.
• Context — application-supplied metadata: tool name, run ID, thread ID, reason.
• Outcome — success, policy denial, provider error, network error.

Sensitive headers (Authorization, Cookie, AWS signing headers) are stripped before storage. The audit record stores call metadata — method, URL, status, latency, and request/response sizes when available — never the request or response body. Capturing request and response payloads is a separate, opt-in feature; see Request and response payload capture below.

For every grant lifecycle event:

• Created, revoked, deleted, scope-drifted, policy-violated.
• Who initiated the event (end user via Wallet, operator via portal, SDK call).

For every administrative action:

• Provider configuration changes, API key mint/rotate/revoke, agent create/update/revoke, identity provider configuration.
• Read-only administrative access, including grant/policy listings, captured-payload views, audit exports, and integrity checks. These rows are classified as Read and their count/offset payload is labeled Read Summary; it is never presented as a created resource or state change.

Successful administrative rows carry an effect classification: Read for data access and Write for state changes. An unsuccessful outcome overrides that intended effect and is classified as Error. An unknown successful action defaults to Write so a newly added mutation cannot disappear from compliance review.

For every user-provisioning event (the Provisioning tab in the portal’s Audit Logs view):

• Users and groups created, updated, or deprovisioned — whether by an IDP webhook, a directory sync run, or a first sign-in.
• Group membership transitions that change access: a member removed (group-grant access revoked) and a membership restored after the member reappears in the directory.
• Each row records the originating path, the outcome (success, no-op, skipped, denied, error), and the reason.

Request and response payload capture

By default, Alter records call metadata in the audit trail — never the request or response body. Capturing request and response payloads is a separate feature that is off by default and turned on per app by an admin in the developer portal under Settings → Payload Capture. Capture can be narrowed to specific agents or end users.

Capture applies wherever the audit trail sees the bodies:

• ✅ app.proxy_request() — backend-mediated execution; the backend captures the bodies it handled.
• ✅ Calls against human-in-the-loop approval grants, which execute on the backend after approval.
• ✅ app.request() — the SDK executes the call itself and reports it to the audit trail; when capture is enabled for the app, the reported request and response bodies are captured from that report.
• ✅ app.boto3_client() (Python SDK only) — every AWS call made through the returned client is routed through the same SDK execution path as app.request(); per-call request and response bodies are reported and captured identically.

Narrowing by end user behaves differently on the two execution paths, deliberately. A backend-executed call is matched against both end-user identities it knows — the grant’s owner and the calling end user. A call the SDK executes and reports is matched against the grant owner only: the caller identity on that report is client-asserted, and an unverified claim is never allowed to widen what a compliance surface records. So a capture list narrowed to a caller-side end user records nothing for SDK-executed calls; narrow by agent, or by the grant owner, to cover both paths.

What is and isn’t stored:

• The caller-supplied request body and the provider response body are captured. Both are size-capped, and an incomplete capture always says so: the stored payload carries a truncation flag and the original size on both execution paths. Calls the SDK executes and reports are capped by the SDK before it reports them — an oversize body is replaced by a placeholder noting its size, and a body that is not valid UTF-8 is replaced by a placeholder whatever its size — and that upstream truncation is recorded on the stored payload rather than being mistaken for a complete body. A captured body from that path is evidence of what was sent, not always a byte-exact copy.
• The injected credential is never captured. The request body is recorded before Alter injects the credential, so a stored payload never contains the secret.
• Captured payloads are a diagnostic tier, not part of the permanent audit record: the default retention window is 30 days, after which they are deleted. They are never included in audit exports.
• Every captured payload records where its bytes came from, and the portal labels it: proxy-captured means Alter observed the bytes itself (it sent the request and received the response); client-reported means the SDK executed the call and reported the bodies, so they are the application’s own account of the call rather than something Alter witnessed. The two are never presented interchangeably.

Captured bodies are visible to app admins from the audit log detail view in the developer portal.

The two questions an audit trail answers

Alter’s audit model is built around two questions that traditional credential systems struggle with:

• “What was Alice’s data used for?” — calls carrying Alice’s app-scoped principal can be filtered by end-user identifier and followed through related keys, grants, and traces.
• “What did Agent X access?” — calls attributed to Agent X can be examined in the app’s grouped-principal and trace views.

The developer portal exposes end-user, managed-agent, provider, action, policy-decision, and time filters, plus key, trace, and thread drill-downs. The CLI supports app, actor, provider, action, policy-decision, and time filters with principal, trace, and thread drill-down commands.

Where to read the audit trail

• Developer portal — every app has an Audit Logs view with filtering, search, and export.
• End-user Wallet — each end user sees the app-scoped slice of the audit trail concerning their own grants, including the application’s reason when supplied.
• Export — see Audit log export for downloads, CLI ingestion, telemetry mirroring, and SIEM delivery.

What’s next

• Audit log export — sending audit logs to an external system.
• Policies — denials are first-class audit events.
• Wallet — what end users see.