AES-256-GCM Encryption & Zero-Knowledge Security

How Token Vault encrypts credentials with AES-256-GCM using either a platform-held key or a webhook-owned key.

All credentials stored in Token Vault are encrypted with AES-256-GCM - a 256-bit authenticated encryption algorithm. AES-256-GCM provides both confidentiality and integrity: data is encrypted with a 256-bit key and a 12-byte initialization vector, and a 16-byte authentication tag ensures that any tampering with the ciphertext is detected on decryption.

Every token document encrypts sensitive fields (access tokens, refresh tokens) individually. Metadata such as the service name, token type, and expiry time is stored in plaintext so the dashboard can display token information without decrypting.

Two Encryption Approaches

The fundamental choice is who holds the encryption key. Token Vault offers two approaches that sit at opposite ends of the trust spectrum.

Loading diagram...

Approach	How it works	Trade-off
Platform Key	Token Vault holds the AES-256-GCM key. Tokens are encrypted at rest, but Token Vault can always decrypt.	Encrypted storage with automatic access. You trust Token Vault with the key.
Webhook-Owned Key	Your webhook generates and holds its own AES-256-GCM key. Token Vault never sees the key. All encryption and decryption happens on your infrastructure.	Full data sovereignty. Token Vault cannot decrypt your credentials. Requires deploying a webhook server.

Platform Key is used in Platform Mode. Webhook-Owned Key is used in Webhook Mode.

Encrypted Document Format

Regardless of which approach you use, the encrypted document format is the same:

Encrypted token document

{
  "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
  }
}

AES-256-GCM Parameters

Parameter	Value
Key	32 bytes (256-bit)
IV	12 bytes (randomly generated per encryption, prepended to ciphertext)
Tag	16 bytes (appended to ciphertext by AES-GCM)
AAD	None (no additional authenticated data)

Each encrypted field value is base64-encoded and contains the IV, ciphertext, and authentication tag concatenated together.

Platform Key Details

In Platform Mode, Token Vault generates and stores the AES-256-GCM key:

A 256-bit key is generated server-side using a cryptographically secure random number generator.
The key is persisted securely server-side, accessible only by Token Vault's backend.
On write: the backend generates a random 12-byte nonce, encrypts with AES-256-GCM, and stores the nonce + ciphertext + tag.
On read: the backend reads the encrypted blob, decrypts with the stored key, and returns the plaintext over TLS.

Webhook-Owned Key Details

In Webhook Mode, your webhook generates and holds its own AES-256-GCM key:

Your webhook generates a 256-bit key during initialization and stores it securely.
When a user stores a credential, the browser sends it directly to your webhook's /v1/store endpoint with a signed ticket. Your webhook encrypts it with its own key and persists it. Token Vault never sees the plaintext.
When an agent requests a credential, Token Vault validates auth and policies, then issues a 307 redirect to your webhook's /v1/credential endpoint. The agent gets the credential directly from your webhook.
When the MCP proxy needs a credential, Token Vault forwards the request to your webhook's /v1/proxy endpoint. Your webhook decrypts and injects the credential into the upstream request.
The key never leaves your infrastructure. Token Vault never sees it.