# Audit Trail

> Coming soon, upon request — this feature is turned on for your tenant by the Aurea team. [Contact us](https://www.aureahub.com/contact)

What was done to your tenant's money, keys, governance, security, settings and access, by whom and on what — newest first.

## Overview

- The trail is append only: an event is never changed or removed. Each event carries the hash of the one before it (`prevHash`) and its own (`hash`, SHA-256 of its content and that link), so the events of your tenant form one chain, numbered from 1 (`seq`).
- An event is written in the same transaction as the action it records: an action whose event cannot be written does not happen.
- `details` holds ids, amounts in the smallest unit, states and codes — never a key, a signature, a secret, a password or a person's data.

## Coming soon, upon request

[Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md) The audit trail is kept for your tenant on request. Until then nothing is recorded, and every request answers an empty page:

```json
{
  "events": [],
  "nextCursor": null
}
```

When it is on, the trail records a wallet's key export (`wallet.key_exported`) and a wallet's deactivation (`wallet.deactivated`), category `keys`, and the changes Aurea makes to your tenant's security profile and its controls (`security_profile.changed`, `security_control.changed`), category `security`. For the [approvals](https://docs.aureahub.com/docs/guide-approvals.md): `approval_key.registered` and `approval_key.revoked`, category `security`; `approval.requested`, `approval.approved`, `approval.rejected`, `approval.threshold_reached`, `approval.expired`, `approval.withdrawn` and `approval.continued`, category `governance`. For the [accounts](https://docs.aureahub.com/docs/guide-accounts.md): `account.created`, `account.updated` and `account.bulk_requested`, category `governance`; `account.wallet_created` and `account.wallet_attached`, category `keys`. For an MPC wallet's [backup proof](https://docs.aureahub.com/docs/mpc-backup-proof-start.md): `mpc_wallet.backup_proof_started` and `mpc_wallet.backup_confirmed`, category `keys`. For [Earn](https://docs.aureahub.com/docs/guide-earn.md): a user's acceptance of a product's disclosure (`earn.disclosure.accepted`, category `money`); and, where Aurea moves Earn's own trail into yours, Earn's operations and redemptions (`earn.operation.*`, `earn.redemption.*`, category `money`) and settings (`earn.settings.saved`, category `settings`), after one `earn.audit_chain_anchored` event that commits to Earn's earlier trail. For [passkeys](https://docs.aureahub.com/docs/guide-passkeys.md): `passkey.registered`, `passkey.revoked`, `passkey.reset`, `step_up.verified` and `step_up.used`, category `access`; an approval decided with a passkey names it (`passkeyId`) in `approval.approved` or `approval.rejected`. For the [Gas Station](https://docs.aureahub.com/docs/guide-gas-station.md): `gas_station.policy.created`, `gas_station.policy.changed` and `gas_station.mode.changed` (Aurea moved your tenant between the gas modes), category `settings`; `gas_station.funding_wallet.created`, category `keys`; `gas_station.topup.signed`, category `money`, by the station. For your [institution callback](https://docs.aureahub.com/docs/guide-institution-callback.md): `institution_callback.settings_changed`, `.decided`, `.expired`, `.cancelled` and `.continued`, category `security`; for your own [MPC co-signer](https://docs.aureahub.com/docs/guide-institution-callback.md): `mpc_cosigner.settings_changed`, category `keys`. For [Agent Payments](https://docs.aureahub.com/docs/agentic-payments.md): an execution's first record (`agent_execution.submitted`) and each change of its state (`agent_execution.state_changed`), category `money`; an agent created (`agent.created`, `settings`), its policy and a mandate (`agent_policy.created`, `mandate.created`, `governance`), a credential issued (`agent_credential.issued`, `security`) and a KYA record (`agent_kya.recorded`, `access`) — the same rows whether the action came through its REST route, an MCP tool (`POST /v1/agent-payments/mcp/call`) or a recurring run (`POST /v1/agent-payments/recurring/run`, an execution's rows per mandate it fires). For your [account structures](https://docs.aureahub.com/docs/guide-account-structures.md): `structure.changed`, `structure.members_added`, `structure.member_removed`, `structure.sweep_policy_set` and `structure.sweep_policy_removed`, category `governance`; `omnibus.withdrawal_requested`, category `money`. For the [asset registry](https://docs.aureahub.com/docs/guide-asset-registry.md): `asset.registered`, `asset.metadata_changed` and `asset.checked`, category `settings` — the names of your metadata's keys, never a value. A wallet's key exported or imported through the direct routes, where Aurea observes key exports and imports for your tenant (nothing is refused for it): `key_ceremony.observed`, category `keys`. More actions are added over time. [Contact us for details](https://www.aureahub.com/contact).

## Who Reads It

- The tenant roles `owner`, `tenantadmin`, `non_signing_admin`, `auditor`, `security_admin` and `security_auditor` ([Roles](https://docs.aureahub.com/docs/authentication.md)) read their own tenant's trail, whatever `tenantId` they send. Any other role answers `403` (`Tenant admin access required. Your role does not have permission to perform this action.`).

## Events

| Field | Meaning |
| --- | --- |
| seq | The event's place in the chain, from 1. |
| category | `money`, `keys`, `governance`, `security`, `settings` or `access`. |
| action | What was done, as dotted lower-case words, e.g. `wallet.key_exported`. |
| actor | Who did it: `kind` (`user`, `service`, `system` or `tenant_api`), `id` and `role`. |
| subject | What it was done to: `type` and `id`, e.g. a wallet. |
| details | The action's own facts; never a secret or a person's data. |
| requestId | The `X-Request-ID` of the request that did it. |
| createdAt | When. |
| prevHash, hash | The chain's links. |

## Endpoint

- The window is `from` (included) to `to` (excluded): by default the last 30 days, at most 366 days per request. Page through a longer period, or through a window with more events than `limit`, with `cursor`: pass the previous page's `nextCursor`, which is `null` on the last page.
- `400` with the message `` `from` must be before `to` ``, or `At most 366 days per request: page through longer periods`.

### `GET /v1/audit-events`

Authentication: bearer token required.

The tenant's audit trail, newest first, in pages.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | string | no | `money`, `keys`, `governance`, `security`, `settings` or `access` |
| `action` | string | no | Only actions starting with this, e.g. `wallet.` |
| `from` | string (date-time) | no | Oldest event time; default 30 days before `to` |
| `to` | string (date-time) | no | Newest event time, excluded; default now. At most 366 days after `from` |
| `cursor` | integer | no | The `nextCursor` of the previous page |
| `limit` | integer | no | 1–500, default 100 |

**Responses**

`200` OK

```json
{
  "events": [
    {
      "seq": 2,
      "category": "keys",
      "action": "wallet.key_exported",
      "actor": { "kind": "user", "id": "5e1f…", "role": null },
      "subject": { "type": "wallet", "id": "7c1e…" },
      "details": { "chain": "ethereum", "isTestnet": false },
      "requestId": "a91099c3593d6c58e547b4aa9f66d9ac",
      "createdAt": "2026-10-05T10:12:00.000Z",
      "prevHash": "4b0c…",
      "hash": "e7a2…"
    }
  ],
  "nextCursor": 2
}
```

`200` Not On

```json
{
  "events": [],
  "nextCursor": null
}
```

`400` Window Too Long

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "At most 366 days per request: page through longer periods"
}
```

**Example request**

```bash
curl "https://api.aureahub.com/v1/audit-events?category=keys&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

Web version: https://docs.aureahub.com/#audit-events