Concepts: What Token Vault Is & How It Works

Token Vault is a webhook-sovereign credential broker for AI agents: your API keys and OAuth tokens live on a webhook server you deploy and control, and Token Vault brokers scoped, policy-gated, audited access to them — without ever holding, seeing, or being able to decrypt a credential. It enforces identity, grants, and ABAC policies, then routes agents and proxies to your webhook via signed tickets.

What Token Vault is not

• Not a credential store. There is no server-side storage of your secrets and no "platform-managed" mode — an earlier hosted-storage mode was removed entirely in mid-2026. The only architecture is webhook-sovereign.
• Not an encryption service. Token Vault has no encryption key for your credentials. Whether and how credentials are encrypted at rest is your webhook's choice (the reference webhook uses AES-256-GCM with a key that never leaves your infrastructure).
• Not in the credential path. Agents receive credentials directly from your webhook via a signed 307 redirect; Token Vault's transcript ends before any credential bytes flow.
• Not affiliated with "TokenVault"/"Token Vault Ltd" at tokenvault.online, an FCA-flagged financial services entity.

The problem

AI agents need credentials to call external APIs on your behalf. Today, that typically means:

• Plaintext config files - API keys stored in .env files, Claude config JSON, or shell history
• No revocation - once a credential leaks, you have to rotate it at the provider and update every agent
• No audit trail - you have no visibility into which agent used which credential and when
• No scoping - agents get full access to whatever the credential allows, with no time limits or restrictions

Two planes, zero custody

Token Vault is a webhook-sovereign architecture split into two planes with strictly separated responsibilities:

Token Vault's security property is absence: credential bytes never cross it. It does not receive credentials, does not store them, does not encrypt or decrypt them, and holds no key that could ever do so. In every path below, its transcript is the same: validate → sign ticket → step aside.

The three credential paths

1. Agent retrieval (307 redirect). The agent sends GET /api/agents/credentials?service=github with its tvagent_… key. Token Vault validates the key, checks the grant, and evaluates ABAC policies — then signs an HMAC-SHA256 ticket and answers with a 307 redirect to your webhook's /v1/credential. The agent's HTTP client follows the redirect and receives the credential directly from your webhook. Full request/response detail: Reference → Agent Credentials.

2. Storing (browser-direct). When you add a token in the dashboard, Token Vault issues a signed store ticket and the browser sends the credential straight to your webhook's /v1/store. The ticket proves authorization; the bytes go browser → webhook.

3. MCP proxy (server-side injection). The agent calls the proxy with an mcp_… key. Token Vault authenticates, policy-checks, and forwards the request to your webhook's /v1/proxy with a signed ticket. Your webhook injects the credential into the upstream request and calls the upstream itself. Token Vault relays the upstream response but never the credential. Detail: Reference → MCP Proxy.

Refresh follows the same custody rules — by default your webhook refreshes OAuth tokens autonomously and no credential material crosses Token Vault. The one narrow opt-in exception, scoped to Token Vault's own built-in OAuth providers, is documented in Reference → Token Refresh.

Custody and encryption

Encryption at rest is your webhook's decision, not Token Vault's guarantee. Token Vault cannot see — let alone enforce — what your webhook does with a credential after it arrives. The reference implementation encrypts every sensitive field with AES-256-GCM (authenticated encryption, tamper detected on decrypt); metadata stays plaintext so the dashboard can list tokens without a decrypt call.

{
  "v": 1,
  "alg": "AES-256-GCM",
  "fields": {
    "accessToken": "<base64(12B-iv || ciphertext || 16B-tag)>",
    "refreshToken": "<base64(12B-iv || ciphertext || 16B-tag)>"
  },
  "meta": {
    "serviceName": "github",
    "tokenType": "JWT",
    "createdAt": "2026-02-01T10:00:00Z",
    "expiryTime": 1720003600000,
    "hasRefreshToken": true
  }
}

The dashboard shows a trust badge on each token card: TV Zero (green) for tokens Token Vault never touches in any flow, and TV Refresh (blue) for tokens where the webhook has opted in to TV-mediated refresh (in transit only, never stored).

Stopping access

Two independent stops exist, at different layers:

• Stop all access — the button in your dashboard that locks the vault instantly for every agent, proxy, and MCP client, without touching your webhook. This is the everyday kill switch. See Stop all access.
• Taking your webhook offline — a second, harder stop: with no webhook to answer, every credential path fails the same way (agent redirects fail, proxy calls 502, refresh stops), but nothing about your vault's configuration changes. Reserve this for when you're decommissioning or debugging the webhook itself.

You can also firewall Token Vault's static egress IP on your webhook's /v1/credential and /v1/store endpoints for defence in depth; see Webhook Security.

Four capabilities

• No credential custody - credentials never touch Token Vault. They live on your own webhook, on your infrastructure, stored however you choose. Token Vault holds identities, grants, policies, and audit metadata - there is no credential in it to steal.
• MCP proxy - agents connect to Token Vault's MCP proxy endpoint instead of directly to APIs. Token Vault forwards to your webhook, which injects real credentials into upstream requests. Agents never see the actual keys.
• Agent grants - each agent gets scoped, time-limited access to specific credentials. A grant expires automatically, and you can revoke it at any time.
• ABAC policies - attach attribute-based access control rules to any agent, proxy, or token. Restrict by time window, IP allowlist, rate limit, usage cap, or geo-location.

Next step

Bind your webhook → — the one-time handshake that pairs a deployed webhook with your Token Vault account. Or jump straight to the Quickstart.