Security and verification basics

Most customers only need three ideas from this page:

1. approved requests return a short-lived token for that specific action
2. Ledgix publishes public signing keys so customers can verify tokens
3. advanced teams can later verify audit evidence with ledger and proof APIs

Approval tokens

When Ledgix approves a request, it returns a token for that exact action. Treat it as:

• short-lived (default exp is 300 seconds; configured by VAULT_JWT_TTL)
• specific to one approved request (a unique jti that is burned on /consume-token)
• safe to forward only to the system that should execute the protected action

It is not a general session token for your application.

Approval tokens are signed with Ed25519 (EdDSA). The token header carries alg: EdDSA and a kid that matches one of the keys published at GET /.well-known/jwks.json. Every token also embeds iss, aud, tool, agent_id, session_id, policy_id, decision, and a tool_args_hash (SHA-256 of the canonical JSON of the approved arguments) so the consuming side can confirm the action has not been tampered with.

Public signing keys

Ledgix exposes a JWKS endpoint so customers can verify approval tokens:

GET /.well-known/jwks.json HTTP/1.1
Host: vault.example.com

Both SDKs can fetch the JWKS and verify tokens automatically. That means most teams do not need to build their own token-verification path unless they want one.

Verifying tokens with the SDK

const claims = await client.verifyToken(clearance.token!);
console.log(claims);

Proof bundles and checkpoints

You do not need proof APIs to finish a first integration. They matter when:

• an auditor asks for tamper-evident evidence
• you want to verify a past request independently of your application logs
• your team is building a formal audit workflow around Ledgix

The easiest advanced verification path is the proof bundle for a single request.

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

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

When customers usually use this page

Read this page after:

• your team already has a working request-clearance flow
• reviewers already know how to handle pending requests
• you need a stronger explanation of how approval tokens or audit verification fit into your compliance story

Security responsibilities that stay with the customer

• store Ledgix API keys securely in your own environment
• forward approval tokens only to the service that should execute the approved action
• rotate credentials when your team changes or environments are rebuilt
• keep a record of request_id values so you can reconcile application events with Ledgix later

Common misconceptions

• An approval token is not a reusable credential for future requests.
• Token verification is helpful, but it does not replace correct application logic around approved, denied, and pending_review.
• Proof APIs are valuable for audit and verification, not a prerequisite for the first guarded tool rollout.