Endpoints

Your webhook implements eight endpoints in three categories. Token Vault calls six of these with HMAC-signed requests. Five are fully hands-off (TV never sees credentials), and one (/v1/refresh) briefly handles credentials in transit during OAuth refresh (never stored). Agents and browsers call the remaining two directly; Token Vault is not in the request path for credential access.

Token Vault → Webhook Endpoints

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

POST /v1/exchange

Called once during the webhook binding flow. Your webhook receives a one-time code and returns its HMAC secret. This is the only endpoint called without HMAC authentication; the code itself is the authentication.

{
  "code": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "hmacSecret": "<base64-encoded 256-bit secret>",
  "webhookId": "wh_abc123",
  "version": "1.0.0",
  "capabilities": ["storage", "credential", "proxy", "refresh", "store", "tv-refresh"]
}

Your webhook should:

1. Validate the one-time code (must be unused, within 5-minute TTL).
2. Generate and store a 256-bit HMAC secret.
3. Return the secret and your webhook's capabilities.
4. Mark the code as used. Reject future exchange attempts with 410 Gone.

GET|POST /v1/health

Called on-demand when the user checks webhook health from the vault settings page, and periodically by Token Vault to monitor status.

GET requests are unauthenticated, useful for external monitoring, load balancers, and the /bind status page. POST requests are HMAC-signed.

{
  "requestId": "req_xyz789abc012"
}

{
  "status": "healthy",
  "version": "1.0.0",
  "capabilities": ["storage", "credential", "proxy", "refresh", "store", "tv-refresh"],
  "uptime": 86400,
  "tokenCount": 5,
  "keyConfigured": true
}

POST /v1/storage

Called for metadata operations only. Token Vault uses this endpoint to list tokens, manage proxy configurations, write audit events, and store vault settings. This endpoint never returns plaintext credentials. Credential access goes through /v1/credential (direct) or /v1/proxy (proxy). Verify HMAC signature before processing.

List tokens (metadata only)

Token Vault calls this to populate the dashboard token list. The response contains metadata only: service names, token types, and expiry times. No plaintext credentials.

{
  "requestId": "req_list_tokens456",
  "operation": "list",
  "collection": "tokens"
}

{
  "requestId": "req_list_tokens456",
  "items": [
    {
      "key": "github",
      "meta": {
        "serviceName": "github",
        "tokenType": "JWT",
        "expiryTime": 1720003600000,
        "createdAt": "2026-02-01T10:00:00Z"
      }
    }
  ]
}

Each item must include key and a meta object with at least serviceName.

Store a proxy config

{
  "requestId": "req_set_proxy789",
  "operation": "set",
  "collection": "proxy_configs",
  "key": "proxy-abc123",
  "data": {
    "name": "GitHub MCP",
    "upstreamUrl": "https://api.github.com/mcp",
    "serviceName": "github",
    "headerTemplates": { "Authorization": "Bearer ${TOKEN}" }
  }
}

{ "requestId": "req_set_proxy789", "status": "ok" }

Delete an item

{
  "requestId": "req_delete_token000",
  "operation": "delete",
  "collection": "tokens",
  "key": "github"
}

{ "requestId": "req_delete_token000", "status": "ok" }

Batch list (multiple collections)

Fetch multiple collections in a single round trip. Used by the dashboard to load tokens and audit events together.

{
  "requestId": "req_batch_list123",
  "operation": "list_batch",
  "collections": ["tokens", "audit"]
}

{
  "requestId": "req_batch_list123",
  "results": {
    "tokens": {
      "items": [
        { "key": "github", "meta": { "serviceName": "github", "tokenType": "JWT" } }
      ]
    },
    "audit": {
      "items": [
        { "key": "2026-02-15T10:30:00Z", "meta": { "event_type": "AGENT_CREDENTIAL_ACCESS" } }
      ]
    }
  }
}

Collections

Audit events

Token Vault writes audit events to the audit collection. Every token access, agent credential retrieval, token refresh, and policy denial is logged here. Your webhook owns this audit trail.

{
  "operation": "set",
  "collection": "audit",
  "key": "2026-02-15T10:30:00Z",
  "data": {
    "event_type": "AGENT_CREDENTIAL_ACCESS",
    "source": "agent",
    "service_name": "github",
    "agent_id": "agent-abc123",
    "client_ip": "203.0.113.42",
    "zero_knowledge": true,
    "timestamp": "2026-02-15T10:30:00Z"
  }
}

POST /v1/proxy

Called when an AI agent makes a request through the MCP proxy. Token Vault validates the proxy key and policies, then forwards the request to your webhook with a signed proxy ticket. Your webhook decrypts the credential, injects it into the upstream request headers (replacing ${TOKEN} placeholders), makes the upstream HTTP call, and returns the response. Token Vault never sees the credential. Verify HMAC signature before processing.

{
  "requestId": "req_proxy_abc123",
  "ticket": "<signed proxy ticket>",
  "service": "github",
  "upstream": {
    "url": "https://api.github.com/mcp",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "<base64-encoded request body>"
  },
  "headerTemplates": {
    "Authorization": "Bearer ${TOKEN}"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
X-Upstream-Status: 200

<upstream response body, passed through verbatim>

Your webhook should:

1. Verify the HMAC signature.
2. Verify the proxy ticket (HMAC, expiry, nonce, purpose = "proxy").
3. Read the encrypted credential for the given service from your storage.
4. Decrypt the credential using your encryption key.
5. Replace ${TOKEN} in headerTemplates with the decrypted access token.
6. Make the HTTP request to upstream.url with the merged headers and body.
7. Return the upstream response to Token Vault as raw HTTP passthrough (same status code, headers, body).

POST /v1/refresh-notify (notify-only)

Called when Token Vault detects a token approaching expiry. Your webhook owns the credential and handles the refresh independently. Token Vault sends metadata (service name, provider hints) but never the credential itself or the clientSecret. Verify HMAC signature before processing.

Use this endpoint for custom OAuth providers where your webhook has its own client credentials configured locally.

{
  "requestId": "req_refresh_abc123",
  "service": "my-custom-api",
  "reason": "token_expiring",
  "expiresAt": "2026-02-17T15:30:00Z",
  "refreshHint": {
    "provider": "my-custom-api",
    "tokenUrl": "https://auth.example.com/oauth/token",
    "clientId": "your_client_id"
  }
}

{
  "requestId": "req_refresh_abc123",
  "status": "refreshed",
  "newExpiresAt": "2026-02-17T16:30:00Z"
}

Your webhook should:

1. Verify the HMAC signature.
2. Read the encrypted token for the given service from your storage.
3. Decrypt the refresh token using your encryption key.
4. Look up your own OAuth client credentials for this provider.
5. Call the OAuth provider's token endpoint with your credentials to get a fresh access token.
6. Encrypt the new tokens and store them back.
7. Return an acknowledgement.

Valid status values:

POST /v1/refresh (TV-mediated)

Called when Token Vault needs to refresh a token for its built-in OAuth providers (Google, GitHub). Unlike /v1/refresh-notify where the webhook handles everything, this enables a two-phase flow where TV performs the OAuth refresh using its own client_secret. Verify HMAC signature before processing.

Capability: Requires "tv-refresh" in your webhook's capabilities list. Without it, TV falls back to /v1/refresh-notify.

Phase 1: Get refresh token

{
  "requestId": "req_refresh_abc123",
  "action": "get",
  "service": "google"
}

{
  "requestId": "req_refresh_abc123",
  "status": "ok",
  "refreshToken": "1//0abc_plaintext_refresh_token...",
  "meta": {
    "serviceName": "google",
    "tokenType": "JWT",
    "expiryTime": 1720003600000,
    "createdAt": "2026-02-01T10:00:00Z"
  }
}

Phase 2: Update with refreshed tokens

{
  "requestId": "req_refresh_abc123",
  "action": "update",
  "service": "google",
  "tokens": {
    "accessToken": "ya29.new_access_token...",
    "refreshToken": "1//0abc_new_or_same_refresh_token...",
    "expiryTime": 1720007200000
  }
}

{
  "requestId": "req_refresh_abc123",
  "status": "updated",
  "newExpiresAt": "2026-07-03T17:00:00+00:00"
}

Your webhook should:

1. Verify the HMAC signature for both phases.
2. Phase 1 (get): Decrypt the refresh token and return it with metadata.
3. Phase 2 (update): Encrypt the new tokens with your key, update the stored document preserving existing metadata (createdAt, tokenType), and return acknowledgement.

Direct Access Endpoints

These endpoints are called directly by agents and browsers. Token Vault is not in the request path. They authenticate with signed tickets (not HMAC headers). Your webhook must verify the ticket's HMAC signature, check expiry, and prevent nonce replay.

GET /v1/credential

Zero-knowledge credential access. This endpoint is hit when an agent follows a 307 redirect from Token Vault, or when a browser requests a credential directly. Token Vault validates the agent's API key and ABAC policies, generates a signed credential ticket, and redirects the agent here. Your webhook verifies the ticket and returns the decrypted credential. Token Vault never sees the credential.

Also accepts POST with a JSON body for browser-based access.

GET /v1/credential?ticket=<signed-ticket>&service=github

{
  "ticket": "<signed-ticket>",
  "service": "github"
}

{
  "token": {
    "accessToken": "ghp_abc123...",
    "refreshToken": "ghr_xyz789...",
    "serviceName": "github",
    "tokenType": "JWT",
    "createdAt": "2026-02-01T10:00:00Z"
  }
}

Your webhook should:

1. Extract ticket and service from query params (GET) or JSON body (POST).
2. Verify the ticket: check HMAC signature, expiry, and nonce (prevent replay).
3. Verify that the ticket's svc field matches the requested service.
4. Read the encrypted credential from your storage.
5. Decrypt using your encryption key.
6. Return the plaintext credential.
7. Set CORS headers if the request comes from a browser (Origin header present).

Ticket payload

The signed ticket is a base64url-encoded JSON payload with an HMAC-SHA256 signature: {base64url(payload)}.{hex_signature}. The payload contains:

{
  "sub": "user-id",
  "svc": "github",
  "pur": "agent_credential",
  "aid": "agent-id",
  "iat": 1708000000,
  "exp": 1708000060,
  "nonce": "random-hex-string"
}

POST /v1/store

Browser-direct credential storage. When a user adds a token through the dashboard, Token Vault issues a store ticket. The browser sends the plaintext credential directly to your webhook with this ticket. Your webhook verifies the ticket, encrypts the credential with its own AES-256-GCM key, and persists it. Token Vault never sees the plaintext credential.

{
  "ticket": "<signed-store-ticket>",
  "service": "github",
  "tokenData": {
    "accessToken": "ghp_abc123...",
    "refreshToken": "ghr_xyz789...",
    "tokenType": "JWT",
    "expiresAt": "2026-02-17T15:30:00Z"
  }
}

{
  "status": "stored",
  "service": "github",
  "meta": {
    "serviceName": "github",
    "tokenType": "JWT",
    "createdAt": "2026-02-15T10:00:00Z"
  }
}

Your webhook should:

1. Verify the ticket: check HMAC signature, expiry, nonce, and purpose ("store").
2. Verify that the ticket's svc field matches the service parameter.
3. Extract the credential data from tokenData.
4. Encrypt sensitive fields (accessToken, refreshToken) with your AES-256-GCM key.
5. Store the encrypted document.
6. Return metadata (not the credential) in the response.
7. Set CORS headers, as this endpoint is called from the browser.

Optional Helper Endpoints

These endpoints are convenience helpers for webhook operators. Token Vault does not call them. They help with registration and management.

GET /v1/register-url

Generates a one-time registration URL programmatically (for CLI/API usage instead of the /bind web page).

{
  "url": "https://tokenvault.uk/vault/webhook-bind?code=550e8400...&webhook_url=aHR0cHM6...&hmac_hash=abc123...",
  "code": "550e8400-e29b-41d4-a716-446655440000",
  "expiresIn": 300
}

GET /bind

A browser-facing HTML page that displays your webhook's status and a "Connect to TokenVault" button. When clicked, it generates a one-time code and redirects the user to Token Vault's bind page.

Query parameters:

• ?force=1 - Generate a new registration code even if the webhook is already bound (re-binding).