XKOVA Docs
Audit Log
Every financial or governed mutation on XKOVA writes an audit row before it is considered done. The row records the authority that was exercised: who acted, the permission they used, the roles they held, and for a quorum action the approvers who attested. The trail is queryable for compliance and activity reporting.
What gets audited
Any mutation in the financial or governed domains is audited: payments, escrows and claims, treasury, fees, governance, policies, break glass, ramps, revenue, compliance, verification, tokenization, and real-world assets. The audit row is part of the action, not a side effect added later, so an action that completed left a record.
What a row records
Each row captures the authority exercised and enough context to reconstruct what happened.
| Field | Meaning |
|---|---|
| action | The canonical event name, for example a payment created or a claim resolved. |
| actor | Who acted, and the actor type: system, staff, account_holder, api_key, or operator. |
| permission | The permission used to authorize the action. |
| roles | The roles the actor held at the time. |
| approvers | For a quorum gated action, the approval request and the approvers who attested. |
| outcome | success, failure, or denied. |
| occurred_at | When the event happened. |
| correlation_id | The request correlation id, also present on errors and webhooks for tracing. |
| before and after | Optional snapshots of the changed resource's state before and after the mutation, when captured; many events carry neither. |
Quorum approved actions and break glass actions carry extra context: the approval request and its approvers, and for break glass a high severity tag. See Policies and Quorum Governance.
Reading the trail
The tenant wide audit trail is queryable by staff. Filter by category, action, actor, target, and date range, sort by occurrence time, and page through with a cursor.
- Tenant audit query.
GET /v1/reports/auditreturns a cursor paginated list of recorded actions for the tenant, with the filters above. The caller needs report-read permission, typically the admin or compliance officer role. - Per resource timeline. A resource's own lifecycle timeline reads from the same trail, for example an escrow's event timeline rendered oldest first.
- Operator activity (console). In the hosted console, an operator can also see their own recent authentication events (sign in, sign out, MFA, scope switch) in the activity panel.
Why this matters
The audit trail is how a governed action proves which authority was used. Combined with the approval quorum and separation of duties, it lets you reconstruct not just that an action happened but that it was authorized correctly and by whom. It is the system of record for compliance and incident review.
Related
See Policies and Quorum Governance for the approvals an audit row references, Roles and Permissions for the permission and role catalog, and the interactive reference for the exact audit read operations and their response shapes.