Credential Retrieval
Token Vault is zero-knowledge. Agents and browsers receive credentials directly from your webhook via signed tickets. Token Vault never sees your credentials.
Token Vault never touches your plaintext credentials. Your webhook owns the encryption key and handles all decryption. Token Vault acts as a policy gate: it decides whether access is allowed, but credential data flows directly between the requester and your webhook.
Agent Credential Access (307 Redirect)
- The agent sends
GET /api/agents/credentials?service=githubto Token Vault. - Token Vault validates the API key, checks grants, and evaluates ABAC policies.
- Token Vault issues a signed credential ticket and returns a 307 redirect to your webhook's
/v1/credentialendpoint. - The agent's HTTP client follows the redirect and receives the credential directly from your webhook.
- Token Vault never sees the credential. It only decided whether access was allowed.
MCP Proxy Access
- The 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/proxywith 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.
Storing Credentials (Browser-Direct)
- The user adds a credential through the dashboard.
- Token Vault issues a signed store ticket.
- The browser sends the credential directly to your webhook's
/v1/storeendpoint. - Your webhook encrypts it with its own AES-256-GCM key and stores it.
- Token Vault never sees the plaintext credential.
Refresh Flow
Two refresh paths are available:
Notify-Only Refresh (/v1/refresh-notify) - fully zero-knowledge:
- Token Vault detects a token approaching expiry and notifies your webhook with provider hints (token URL, client ID).
- Your webhook reads the encrypted token from its storage, decrypts the refresh token, calls the OAuth provider using its own client credentials, encrypts the new token, and stores it back.
- Token Vault never sees any credential material.
TV-Mediated Refresh (/v1/refresh) - opt-in, transit-only handling:
- Token Vault asks your webhook for the decrypted refresh token (Phase 1:
action: get). - Token Vault calls the OAuth provider (Google, GitHub) with its own
client_secret. - Token Vault sends the fresh tokens back for your webhook to encrypt and store (Phase 2:
action: update).
TV-Mediated Refresh: how OAuth tokens are handled
This is the only flow where Token Vault briefly handles credential material in transit. Token Vault does not and will never store your credentials. Your webhook opts in by reporting the tv-refresh capability during /v1/exchange. Without it, Token Vault uses notify-only refresh and never touches credentials at all. The webhook remains the kill switch: take it offline and Token Vault cannot access any tokens.
The dashboard shows trust model badges on each token card: TV Zero (green) for tokens Token Vault never touches, and TV Refresh (blue) for tokens where TV handles the refresh in transit.
The Kill Switch
Taking your webhook offline instantly locks the vault:
- Token Vault cannot access any credentials because your webhook owns the key.
- All agent redirect requests fail (webhook unreachable).
- All MCP proxy requests return 503.
- Token refresh stops.
- Bring the webhook back online and everything resumes.
This is the emergency revocation mechanism. See Webhook Mode for details.
AES-256-GCM Encryption & Zero-Knowledge Security
How Token Vault's webhook-sovereign architecture keeps your encryption key on your infrastructure. Token Vault never holds or sees your AES-256-GCM key.
Agent Grants: Scoped, Time-Limited Credential Access
Give your AI agents scoped, time-limited access to vault credentials.