Security
URL validation requirements, the kill switch mechanism, and security best practices for your webhook service.
URL Validation Requirements
When registering a webhook URL, Token Vault enforces strict validation to prevent SSRF attacks:
- Must use HTTPS (no HTTP).
- Must have a valid, resolvable hostname.
- No private IP addresses (
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.0/8, IPv6 loopback/link-local). - Port must be 443 or > 1024.
- DNS resolution must not resolve to a private IP.
Token Vault Static IP
Token Vault's Cloud Run backend uses a static NAT IP for all outbound requests to your webhook:
34.12.35.243IP Whitelisting Strategy
Use this IP to implement defence-in-depth. Different endpoints should have different IP rules:
| Endpoint | Allow from TV IP? | Rationale |
|---|---|---|
/v1/health | Yes | Token Vault calls this for health checks |
/v1/storage | Yes | Token Vault calls this for metadata CRUD |
/v1/proxy | Yes | Token Vault forwards proxy requests here |
/v1/refresh-notify | Yes | Token Vault sends refresh notifications |
/v1/refresh | Yes | Token Vault calls for TV-mediated refresh |
/v1/credential | No | Agents reach this via 307 redirect from their own IP |
/v1/store | No | Browsers call this directly |
Why block Token Vault on credential/store endpoints?
If Token Vault's infrastructure were compromised, blocking its IP on /v1/credential and /v1/store ensures it cannot directly exfiltrate credentials. Agents reach these endpoints by following the 307 redirect from their own IP. This is the network-level zero-knowledge guarantee.
Use the Debug & Testing Tools to verify your IP filtering is correctly configured.
The Kill Switch
Taking your webhook offline is an instant kill switch. Your webhook owns the encryption key and all credential data. Without it, Token Vault cannot decrypt anything. All agents, MCP proxies, and token refresh stop immediately. Bring the webhook back online and everything resumes.
HMAC Verification
Always verify HMAC signatures
Your webhook must verify the HMAC-SHA256 signature on every request before processing it. The only exception is /v1/exchange, which uses a one-time code for authentication instead.
A request with an invalid or missing signature should be rejected with HTTP 401. Never process the request body if the signature check fails.
Security Best Practices
Security checklist
- Verify HMAC on every request - reject with
401if the signature does not match. - Store the HMAC secret in a secrets manager, not in plaintext config files.
- Reject timestamps more than 5 minutes old to prevent replay attacks.
- Track request IDs to prevent duplicate processing.
- Use TLS 1.2+ for all webhook communication.
- Log all incoming requests for your own audit trail.
- Encrypt credentials at rest using AES-256-GCM with a key you control.
- Block Token Vault's IP (
34.12.35.243) on/v1/credentialand/v1/storefor network-level zero-knowledge.
Verifying Your Webhook Security
Token Vault includes built-in security tests accessible from the Webhook Endpoint Tester at /debug/webhook. These tests verify your webhook correctly rejects unauthorized requests:
Forged Credential Ticket
Sends a credential ticket signed with a random (incorrect) HMAC key. Your webhook must reject this with 401. If accepted, any attacker who discovers your webhook URL could bypass Token Vault and steal credentials directly.
Real Ticket from Token Vault IP
Sends a correctly signed ticket from Token Vault's server IP (34.12.35.243). If your webhook has IP filtering configured, this should be rejected. Token Vault should never call /v1/credential directly. If accepted, the test reports a warning (HMAC still protects the request, but there is no network-level isolation).
Forged Store Ticket
Sends a store ticket with an incorrect HMAC signature. Your webhook must reject this with 401. If accepted, attackers could overwrite stored credentials with malicious values.