Customer developer docs

Ledger and proof verification

Use ledger, checkpoint, and proof endpoints when your team needs advanced audit verification.

Ledger and proof verification

This page is for customers who need more than the day-one request flow. Use it when you want to inspect past requests, confirm what was recorded, or verify a single request with proof APIs.

Which endpoint to use

FieldTypeRequiredDescription
GET /ledgerHistoryNoList recent request records for your tenant.
GET /ledger/checkpointsHistoryNoList recent signed checkpoints for your tenant.
GET /ledger/verifyVerificationNoRun Ledgix server-side verification over recent ledger data.
GET /ledger/proof/bundleVerificationNoFetch the recommended per-request verification bundle.
GET /ledger/proof/inclusionVerificationNoFetch the inclusion proof for one request.
GET /ledger/proof/consistencyVerificationNoFetch a consistency proof between two checkpoints.
GET /ledger/encryptedAdvancedNoFetch a richer protected ledger payload when your integration needs it explicitly.

Most customers who need verification should start with a proof bundle, not with individual ledger primitives.

text
GET /ledger/proof/bundle?request_id=8ee2d480-4e23-49c5-9869-a0247e806e1c HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example

That bundle gives you the request event, its inclusion proof, and the key material the SDK needs for verification.

Example SDK verification

typescript
const bundle = await client.fetchLedgerProofBundle(requestId);
const result = await client.verifyLedgerProofBundle(bundle);

if (!result.intact) {
throw new Error(result.error ?? "Verification failed");
}

Listing recent request history

Use /ledger when your team wants a recent history of approved or denied requests.

text
GET /ledger?limit=50 HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example

Use /ledger/checkpoints when you want the recent checkpoint list instead:

text
GET /ledger/checkpoints?limit=24 HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example

When to use the lower-level proof endpoints

Use them only if your verification flow needs them directly:

  • /ledger/proof/inclusion for a specific request
  • /ledger/proof/consistency for comparing two checkpoints

Example:

text
GET /ledger/proof/inclusion?request_id=8ee2d480-4e23-49c5-9869-a0247e806e1c HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example
text
GET /ledger/proof/consistency?from=41&to=42 HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example

When to use /ledger/encrypted

Most customers can ignore /ledger/encrypted. It exists for advanced integrations that need a richer protected ledger payload than the standard public ledger list.

If you are not sure whether you need it, you probably do not. Start with:

  • /ledger for history
  • /ledger/proof/bundle for verification

Practical rules

  • Keep the request_id from the original request so you can fetch the matching bundle later.
  • Use proof bundles for per-request verification before building a custom checkpoint workflow.
  • Treat ledger and proof APIs as audit surfaces, not as a replacement for handling request statuses correctly in your application.