# Download Ledger

`GET /vault/audit-ledger` · Keys & Secrets · Audit Ledger

Returns the project's ledger events in sequence order, optionally limited to the range `from` to `to`. The `X-K9O-Ledger-Signature` header carries an RSA-SHA256 signature over the body, base64. Verify it with Get Signing Keys, and recompute the hash chain: each event's `previousHash` is the `hash` of the event before it. Needs `PROJECT_ADMIN` or `PROJECT_AUDITOR`.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectId` | query | yes | The project's id. Example: `"3f2c9a4e-8b1d-4c6f-9e2a-7d5b1c0a4e8f"`. |
| `from` | query | no | The first ledger sequence number to return, inclusive. Without it, the ledger starts at its first event. Example: `1`. |
| `to` | query | no | The last ledger sequence number to return, inclusive. Without it, the ledger runs to its latest event. Example: `250`. |
| `format` | query | no | The response format. `json` is the only one; any other value returns 415. Example: `"json"`. |

## Responses

- **200**: The ledger events, signed.

| Field | Type | Required | Description |
|---|---|---|---|
| `[]actorId` | string | yes | Actor identifier — the subject (user or system) that produced the event. Example: `"usr_7Hq2LmN9pR4s"`. |
| `[]canonicalPayloadBytes` | string | yes | The event's payload as canonical JSON (JCS) text, exactly the bytes the hash covers. Verify against this field, never `payload`. Example: `"{\"keyId\":\"vkey_7Rt2Wq9LxP4m\",\"newVersion\":4,\"previousVersion\":3}"`. |
| `[]eventId` | string | yes | UUID identifying the event. Example: `"5b0e8f3a-2c1d-4e7b-9a6f-0d1c2b3a4e5f"`. |
| `[]eventType` | enum ("CUSTODY_MODE_TRANSITION", "ATTESTATION", "BYOK_ATTACHED", "BYOK_DETACHED", "HYOK_ATTACHED", "HYOK_DETACHED", "KEY_PROVISIONED", "KEY_ROTATION_STARTED", "KEY_ROTATION_COMPLETED", "KEY_ROTATION_FAILED", "KEY_REVOKED", "KEY_ZEROIZING", "KEY_PURGED", "KEY_EXPORTED", "SUBJECT_ERASED", "RESIDENCY_CLASS_CHANGED", "CROSS_BORDER_SERVED", "DEPROVISIONING_STARTED", "DEPROVISIONING_COMPLETED", "SECRET_PATH_CHANGED", "MEASUREMENT_POLICY_SET", "MEASUREMENT_ADDED", "MEASUREMENT_REVOKED", "WARDEN_GATE_DECISION", "MKEK_RELEASE_POLICY_OPENED", "MKEK_RELEASE_POLICY_CLOSED", "SECRET_KEY_ROTATED", "SECRET_ZEROIZED", "SECRET_STANDARD_ACCESS", "SECRET_PRIVILEGED_ACCESS", "SECRET_REVEAL_CHALLENGE_REJECTED", "SECRET_RETIRED", "KEY_ZEROIZE_ABORTED", "LEDGER_RESTORED", "TELEMETRY_DAY_KEY_EXPIRED", "EXTENSION_SEALED_DATA_RESEALED", "OAUTH_REFRESH_ROTATED", "OAUTH_CREDENTIAL_BLOCKED", "SIGNING_KEY_MINTED", "SIGNING_KEY_RETIRED", "DISCOVERY_OPRF_KEY_MINTED", "DISCOVERY_OPRF_KEY_ACTIVATED", "DISCOVERY_OPRF_KEY_RETIRED", "END_USER_CREDENTIAL_STORED", "END_USER_CREDENTIAL_ROTATED", "END_USER_CREDENTIAL_BLOCKED", "END_USER_CREDENTIAL_DELETED", "INSTALL_CLIENT_SECRET_STORED", "INSTALL_CLIENT_SECRET_ROTATED", "INSTALL_CLIENT_SECRET_REVOKED", "DISCOVERY_OPRF_KEY_RESEALED", "WALLET_SIGNATURE_ISSUED", "APP_SEALED_DATA_RESEALED", "KMS_FEDERATION_TOKEN_ISSUED", "INSTALL_TOKEN_STORED", "INSTALL_TOKEN_CONFIRMED", "INSTALL_TOKEN_ROTATED", "INSTALL_TOKEN_DISCARDED", "PROJECT_PURGE_CONSENT_RECORDED", "PROJECT_PURGE_CONSENT_CANCELLED", "PROJECT_CREDENTIALS_RETIRED", "PROJECT_CREDENTIALS_RECOVERED", "PROJECT_CREDENTIALS_SHREDDED", "PROJECT_CREDENTIALS_REVOCABLE_READ", "KEY_ERASURE_CONFIRMED") | yes | Signed-audit-ledger event types. |
| `[]hash` | string | yes | Hex-encoded SHA-256 hash of this event's canonical serialization. Example: `"60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752"`. |
| `[]orgId` | string | yes | Org this project belongs to. Example: `"org_8kP3wQ9zLm2X"`. |
| `[]payload` | object | yes | The event's payload as a JSON object, for reading and filtering. Its keys depend on `eventType`. It isn't the hash input: verify against `canonicalPayloadBytes`. Example: `{"keyId":"vkey_7Rt2Wq9LxP4m","previousVersion":3,"newVersion":4}`. |
| `[]previousHash` | string \| null | no | Hex-encoded SHA-256 hash of the previous event; explicit `null` for the genesis event (always serialized, never omitted, so it participates in the canonical hash preimage). Example: `"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"`. |
| `[]projectId` | string | yes | Project this event belongs to. Example: `"3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b"`. |
| `[]sequenceNumber` | integer (int64) | yes | Monotone sequence number; `1` for the genesis event. Example: `1842`. |
| `[]timestamp` | string (date-time) | yes | Event timestamp — canonical millisecond-precision RFC 3339 with a `Z` suffix (always exactly 3 decimals, including `.000`), matching the timestamp string the event hash was computed over. Example: `"2026-11-15T09:30:00.123Z"`. |


## Errors

| HTTP | Description |
|---|---|
| 401 | The request carries no authenticated caller. |
| 415 | `format` isn't `json`. |
| 500 | An internal error. Retry later. |

## Code samples

### cURL

```bash
curl -X GET 'https://<org>.api-<region>.k9o.io/@storefront/vault/audit-ledger' \
  -H 'Authorization: Bearer $K9O_TOKEN'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/vault/audit-ledger', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`
  },
});
const { data, meta } = await res.json();
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/keys-secrets/download-ledger
