Webhook Integration

In Webhook Mode, Token Vault never sees your plaintext credentials. Your webhook owns the encryption key, stores all credential data, and handles decryption. Token Vault is a metadata, policy, and authorization layer only.

Your webhook serves two kinds of endpoints:

The Core Principle

Token Vault never accesses your credentials. Every operation that touches plaintext credential data happens between the agent/browser and your webhook directly. Token Vault is not in the path:

• Storing tokens: the browser sends credentials directly to your webhook's /v1/store endpoint with a signed ticket. Token Vault issues the ticket but never sees the credential.
• Agent access: Token Vault validates the agent's API key and policies, then issues a 307 redirect to your webhook's /v1/credential endpoint. The agent follows the redirect and gets the credential directly from your webhook. Token Vault never touches it.
• MCP proxy: Token Vault forwards the proxy request to your webhook's /v1/proxy endpoint with a signed ticket. Your webhook decrypts the credential, injects it into the upstream request, and returns the response. Token Vault sees the upstream response but never the credential.

Protocol Version

The current protocol version is 2.2.0. All endpoints are prefixed with /v1/. Webhook implementations should return their version in /v1/health responses.

Endpoint Summary

Your webhook implements eight endpoints, split into two categories:

Token Vault → Webhook (HMAC-signed)

These endpoints are called by the Token Vault backend. Every request (except /v1/exchange) is signed with HMAC-SHA256.

Direct Access (NOT called by Token Vault)

These endpoints are called directly by agents and browsers. They authenticate with signed tickets issued by Token Vault, not HMAC headers. Token Vault is not in the request path.

How It Works

1. Registration

Token Vault generates a one-time code. Your webhook exchanges it via /v1/exchange to establish the shared HMAC secret.

2. Storing a credential

The user adds a token through the dashboard. Token Vault issues a store ticket and the browser sends the credential directly to your webhook's /v1/store endpoint. Your webhook encrypts it with its own AES-256-GCM key and persists it. Token Vault never sees the plaintext.

3. Agent credential access

An agent requests a credential from Token Vault. Token Vault validates the API key, checks grants and ABAC policies, then returns a 307 redirect to your webhook's /v1/credential endpoint with a signed ticket. The agent follows the redirect and receives the credential directly from your webhook. Token Vault only decides whether access is allowed; it never touches the credential.

4. MCP proxy

An agent makes a request through the MCP proxy. Token Vault validates the proxy key and policies, then forwards the request to your webhook's /v1/proxy endpoint with a signed ticket. Your webhook decrypts the credential, injects it into the upstream request headers, makes the upstream call, and returns the response.

5. Token refresh

Two refresh paths are available:

• Notify-only (/v1/refresh-notify): Token Vault sends provider hints (token URL, client ID). Your webhook owns the entire OAuth refresh cycle using its own client credentials. Token Vault never sees credential material. Use this for custom OAuth providers.
• TV-mediated (/v1/refresh): Token Vault retrieves the refresh token from your webhook, performs the OAuth refresh using its own client credentials (Google, GitHub), and sends the new tokens back for your webhook to encrypt. Credentials are in transit only and never stored. Opt in via the tv-refresh capability.

Generate with AI

Token Vault publishes a complete machine-readable specification at /llm.txt. This file contains every endpoint schema, request/response format, authentication details, and implementation notes in a format optimized for LLM consumption.

Feed it to your preferred AI assistant along with your language and framework of choice to generate a working webhook implementation:

curl -s https://tokenvault.uk/llm.txt | pbcopy

Example prompt:

Here is the Token Vault webhook specification. Generate a complete webhook server implementation in Python using FastAPI. Include all seven endpoints, HMAC verification middleware, ticket verification, AES-256-GCM encryption, a SQLite storage backend, and inline comments explaining each step.

Getting Started