Audit events

The immutable trail behind every mutation, resolve, and reveal — what is recorded, for how long.

Every consequential action leaves an immutable record: who (actor_id, with roles), did what (event_type), to which credential of which provider, when, and under which correlation_id. Metadata carries structured context — changed field names, resolve flags, failure reasons — and never secret values.

Read it via GET /v1/admin/audit-events (provider_admin/auditor humans) or GET /internal/v1/admin/audit-events (operator tooling), filtering by event_type, provider_code, credential_id, actor_id, and a from/to time window.

Event types

Event	When
`credential.created` / `credential.updated`	create; rename/reconfigure/rotation (metadata lists changed fields)
`credential.default_changed`	make-default and replacement promotions
`credential.disabled` / `credential.enabled` / `credential.deleted`	lifecycle transitions (Defaults and Lifecycle)
`credential.resolved`	every [[Resolve-Chain
`credential.resolve_failed`	every resolve miss — with the failure reason and context
`credential.revealed`	every [[Reveal
`credential.decryption_failed`	ciphertext that would not decrypt, with the operation (`resolve`/`reveal`)
`credential.purged`	physical deletion after the recovery window

Actor forms tell the planes apart: a user UUID on the user plane; service:<client_id> for plain service calls; service:<client_id>!<operator> when the Internal Admin API attributes a named operator.

Retention

The trail is capped (default 10 days) and purged daily; the recovery window for soft-deleted credentials is separate (default 5 days). Two consequences:

Export what you must keep. Compliance archives belong downstream; page through the API and store events on your side.
credential.revealed is exempt from purge. The retention window was sized for the flood of credential.resolved events, not for the one trace a human's access to plaintext leaves — that one stays.

Worked example (filter the trail down to one credential's story): cookbook scenario 09.