Vault API reference

Vault is the customer-facing Ledgix API. Use it directly when you are not relying on one of the SDKs, or when you need to automate tenant settings, review, reports, or drift operations from your own systems.

Authentication

Send your tenant API key on every authenticated request:

X-Vault-API-Key: sk_prod_example

Unauthenticated endpoints:

• GET /health
• GET /.well-known/jwks.json
• GET /reports/shared/{token} and GET /reports/shared/{token}/artifacts/{format}

Admin operator endpoints require a Bearer token or X-Admin-API-Key and live under /admin/.... They are not part of the customer surface documented here.

Endpoint map

Request clearance

Request body

POST /request-clearance HTTP/1.1
Host: vault.example.com
Content-Type: application/json
X-Vault-API-Key: sk_prod_example
 
{
  "tool_name": "create_stripe_payment",
  "tool_args": {
    "amount": 249.99,
    "currency": "USD",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "order_event_id": "ord_evt_2048",
    "reasoning": "Charge matches a completed order event."
  },
  "agent_id": "payments-agent",
  "session_id": "checkout-42",
  "context": {
    "policy_id": "payments-prod"
  }
}

Response body

Polling request status

Use this endpoint when a request is still processing or pending_review.

GET /clearance-status/8ee2d480-4e23-49c5-9869-a0247e806e1c HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example

The response shape matches POST /request-clearance.

Consuming the A-JWT at the tool boundary

Call /consume-token from the service that actually performs the protected action (or from the tool-gateway binary placed in front of it). Vault verifies the Ed25519 signature, checks iss / aud / exp, and burns the jti so the token cannot be replayed.

POST /consume-token HTTP/1.1
Host: vault.example.com
Content-Type: application/json
X-Vault-API-Key: sk_prod_example
 
{
  "token": "eyJhbGciOiJFZERTQSIsImtpZCI6InZhdWx0LWtleS0wMDEifQ..."
}

Response:

A replay returns HTTP 409 Conflict. Treat this as a hard fail — do not execute the protected action.

Registering structured policies

Use this endpoint when your application already stores a compact rule set.

POST /register-policy HTTP/1.1
Host: vault.example.com
Content-Type: application/json
X-Vault-API-Key: sk_prod_example
 
{
  "policy_id": "payments-prod",
  "description": "Controls automated payment creation",
  "rules": [
    "Payments must be tied to a valid order event.",
    "Automated payments above $1000 require manual review.",
    "Payment methods must use tokenized identifiers."
  ],
  "tools": ["create_stripe_payment"]
}

Review settings

Read the threshold

GET /review-settings HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example

Update the threshold

PUT /review-settings HTTP/1.1
Host: vault.example.com
Content-Type: application/json
X-Vault-API-Key: sk_prod_example
 
{
  "minimum_confidence_score": 0.9
}

Notification settings

Read current settings

GET /notification-settings HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example

Update current settings

PUT /notification-settings HTTP/1.1
Host: vault.example.com
Content-Type: application/json
X-Vault-API-Key: sk_prod_example
 
{
  "email_enabled": true,
  "email_recipients": "ops@example.com,security@example.com",
  "slack_enabled": true,
  "slack_webhook_url": "https://hooks.slack.com/services/..."
}

Review queue

List review items

GET /reviews?status=pending_review&limit=100 HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example

Finalize a request

POST /reviews/8ee2d480-4e23-49c5-9869-a0247e806e1c/decision HTTP/1.1
Host: vault.example.com
Content-Type: application/json
X-Vault-API-Key: sk_prod_example
 
{
  "approved": false,
  "review_reason": "Order event could not be validated.",
  "reviewer_email": "operator@example.com"
}

Compliance reports

Vault can generate SOX 404 compliance reports on demand and share them with external reviewers via signed tokens.

GET  /report-settings
PUT  /report-settings
GET  /reports
POST /reports
GET  /reports/{reportID}
GET  /reports/{reportID}/artifacts/{format}
POST /reports/{reportID}/share

The format path component accepts the artifact format configured for that report (typically pdf or json). POST /reports/{reportID}/share returns an opaque token that can be exchanged at the public GET /reports/shared/{token} endpoint without an API key.

Drift detection

Drift monitors per-agent behavior and can fail-close a specific agent if its pattern diverges from the approved baseline.

GET    /drift/settings
PUT    /drift/settings
GET    /drift/summary
GET    /drift/events
POST   /drift/agents/{agentID}/lockdown
DELETE /drift/agents/{agentID}/lockdown

A locked-down agent causes POST /request-clearance to deny without evaluating the policy. Release the lock only after human review.

Ledger and verification

Use these when your team wants to audit history or independently verify the cryptographic chain:

• GET /ledger — encrypted ledger entries for your tenant
• GET /ledger/verify — recompute and verify the Merkle tree end-to-end
• GET /ledger/verification-summary — compact status (latest checkpoint, anchor state, key versions)
• GET /ledger/checkpoints (alias GET /ledger/manifests) — sealed Merkle checkpoints
• GET /ledger/proof/inclusion?request_id=... — inclusion proof for one request
• GET /ledger/proof/consistency?from=...&to=... — consistency proof between checkpoints
• GET /ledger/proof/bundle?request_id=... — combined per-request proof bundle
• GET /.well-known/jwks.json — Ed25519 public keys for A-JWT verification

Error handling

The most important customer-facing failure modes are:

• 401 Unauthorized when the API key is missing, deleted, or wrong for the environment
• 400 Bad Request when the payload is malformed or required fields are missing
• 409 Conflict on /consume-token when the JWT has already been burned — do not retry
• pending_review when the request needs a human reviewer before it can continue

Treat pending_review as workflow, not as an exception case that should be retried blindly.