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:
request_mandate,get_mandate,charge,get_chargeandexport_evidence.- Agents get no tool to modify or revoke a mandate.
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 |
- Signature: every delivery carries
Forlabs-Vault-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "t." + body)>. Verify it withforlabs_vault.webhooks.verify(body, header, secret). - Retries: each delivery is tried once, then retried 3 times (after 30s, 2m and 10m). After that it is marked failed and recorded on the chain.
- Local testing: test-mode tenants may use
http://localhost. To reach a server on your machine from the hosted sandbox, use a tunnel such ascloudflared tunnel --url http://localhost:3000and register the https URL it prints.
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}.
next_actionis one ofrequest_approval,request_new_mandateornone.- Messages follow
Accept-Language(ko/en). - Policy denials return HTTP 402 with the recorded
charge.
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.