Forlabs Vault docs

Forlabs Vault

Spending limits and an audit trail for AI agents that pay. The user signs the limits once with a passkey. The vault enforces them on every charge and records every decision so that tampering is always detectable.

Quickstart: first test charge from your agent

1. Get a sandbox key (no signup, no PG account, no card):

curl -s -X POST https://sandbox.vault.forlabs.io/v1/sandbox/keys
# → {"api_key": "sk_test_…", "mcp_url": "https://sandbox.vault.forlabs.io/mcp", …}
export VAULT_TEST_KEY=sk_test_…

2. Add the MCP server.

Claude Code:

claude mcp add --transport http forlabs-vault https://sandbox.vault.forlabs.io/mcp \
  --header "Authorization: Bearer $VAULT_TEST_KEY"

Cursor (.cursor/mcp.json):

{"mcpServers": {"forlabs-vault": {"url": "https://sandbox.vault.forlabs.io/mcp",
  "headers": {"Authorization": "Bearer sk_test_…"}}}}

3. Ask your agent: "Propose a mandate for user me: 300,000원 total, 50,000원 per charge, ask me above 30,000원, merchant coupang/쿠팡, until the end of the month." The agent calls request_mandate, which returns a sign_url.

4. Open the sign_url and sign with a passkey. The first time, this creates the passkey. The agent can only propose; the mandate takes effect when you sign.

5. Ask: "Charge 12,000원 at coupang for 생수." → succeeded, with a signed receipt. Then try:

Amount Result
4,040원 Declined (SANDBOX_DECLINED); the limit is released
5,030원 unknown; still counts against the limit until reconciled
30,001원 pending_approval, next_action: request_approval. In the sandbox the response includes approve_url; open it and approve with your passkey
50,001원 Denied with next_action: request_new_mandate

6. Ask the agent to export_evidence, then verify the bundle offline:

curl -s https://sandbox.vault.forlabs.io/v1/receipt-keys     # pin this key
uv run python -m verifier bundle.json --receipt-key KID:X \
  --origin https://sandbox.vault.forlabs.io --rp-id sandbox.vault.forlabs.io \
  --tsa-root server/trust/sslcom-root-rsa.pem

MCP tools:

REST equivalents:

Purpose Endpoint
Mandates POST /v1/mandates, GET /v1/mandates/{id}
Charges (Idempotency-Key header required) POST /v1/charges, GET /v1/charges/{id}
Evidence GET /v1/mandates/{id}/evidence
Reconcile unknown and stale reserved charges POST /v1/reconcile/charges
Match the PG ledger 1:1 against the chain POST /v1/reconcile/ledger {start, end}
Receipt public keys GET /v1/receipt-keys

Outside the sandbox you send a tenant-signed user_token (an EdDSA JWT) and an instrument_id from POST /v1/instruments.

Webhooks

PUT /v1/webhook-endpoint {"url": "https://…"} returns the signing secret. It is shown once only, and calling the endpoint again rotates it.

Event When
approval.requested A charge was escalated. Includes approve_url; send it to the user. Outside the sandbox this webhook is the only place the link appears
approval.resolved The user approved or rejected, or the request expired (after 10 minutes)
charge.settled An approved charge finished at the PG
credential.registered A passkey was enrolled. Alert your user if they didn't do it
mandate.signed Includes revoke_url; show it in your UI
mandate.declined The user declined to sign
mandate.revoked The user revoked the mandate
mandate.integrity_failed The stored mandate no longer matched the user's signature, so charges on it were refused. Treat it as a security incident and contact support

Revocation

Only the user can revoke a mandate, with their passkey. The revoke link appears on the signing done page, in the copy email and in the mandate.signed webhook. Agents get no revoke tool. After revocation, new charges get mandate_revoked. Charges already in flight finish normally.

Errors

Every error uses the same envelope: {type, code, message, param, doc_url, request_id, next_action}.

Versioning

The API is /v1. Before any breaking change we give 90 days' notice in the changelog and in the response header Sunset. We add fields without notice.

Feedback

Building an agent that pays? Tell us what blocked you. Email support@forlabs.io, or send it from your backend with your API key (it reaches the same inbox):

curl -X POST https://sandbox.vault.forlabs.io/v1/feedback \
  -H "Authorization: Bearer $VAULT_TEST_KEY" -H "Content-Type: application/json" \
  -d '{"message": "charge returned 402 and next_action was unclear",
       "contact": "you@example.com", "context": {"charge_id": "chg_..."}}'
# 202 {"received": true}

message is 1–4000 characters; contact (where we can reach you) and context (any JSON object up to 8 KB: ids, SDK version, the error you got) are optional.