Docs/Concepts/How the Vault Works

How the Vault Works

Understand Keystore's proxy architecture — how agent tokens are resolved into real credentials at request time without exposing secrets.

How the Vault Works

Keystore is a credential vault and reverse proxy. Your agent code never holds real API keys. Instead, it sends requests with a ks_ agent token, and the Keystore proxy resolves the real credentials at request time.

The request flow

Every API call from your agent goes through five steps:

1
2
3
4
5
6
7
8
9
10
Agent Code           Keystore Proxy           Provider API
    |                     |                        |
    |-- ks_ token ------->|                        |
    |                     |-- 1. Validate token    |
    |                     |-- 2. Check scopes      |
    |                     |-- 3. Decrypt credential |
    |                     |-- 4. Inject real key -->|
    |                     |                        |
    |                     |<-- Response -----------|
    |<-- Response --------|                        |

Step 1: Validate the token

The proxy receives the request and extracts the ks_ token from the authorization header. It computes the SHA-256 hash of the token and looks it up in the database. If the token is invalid, expired, or revoked, the request is rejected immediately.

Step 2: Check scopes and limits

The proxy verifies that the token is authorized for the requested provider and operation. It also checks budget limits and rate limits. If the request would exceed a configured threshold, it is rejected with a clear error message.

Step 3: Decrypt the credential

The real API key is stored encrypted with AES-256-GCM. The proxy decrypts it in memory using the project's encryption key. The plaintext key exists only in process memory for the duration of the request and is never logged or persisted.

Step 4: Inject and forward

The proxy replaces the ks_ token with the real API key in the appropriate header (e.g., Authorization: Bearer sk-... for OpenAI, x-api-key for Anthropic) and forwards the request to the provider's actual API endpoint.

Step 5: Return the response

The provider's response is passed back to your agent unmodified. The proxy logs metadata (provider, status code, latency, estimated cost) but never logs request or response bodies.

How interception works

The TypeScript SDK's interceptAll() method patches globalThis.fetch to intercept outgoing requests. It maintains a map of provider hostnames (e.g., api.openai.com, api.anthropic.com) and rewrites matching requests to the proxy URL:

1
2
Original:  https://api.openai.com/v1/chat/completions
Rewritten: https://proxy.keystore.sh/v1/openai/v1/chat/completions

The Python SDK does the same thing with httpx transport-level patching, since the OpenAI and Anthropic Python SDKs use httpx under the hood.

When you call restore(), the original fetch (or httpx transport) is restored and requests go directly to provider APIs again.

What the proxy sees

DataLogged?
Agent token hashYes
Provider slugYes
HTTP method and pathYes
Response status codeYes
LatencyYes
Estimated costYes
Request bodyNo
Response bodyNo
Real API keyNo

Security properties

  • Zero-knowledge forwarding. The proxy decrypts credentials in memory and injects them into the outgoing request. Plaintext keys are never written to disk or logs.
  • Token hashing. Agent tokens are stored as SHA-256 hashes. Even if the database is compromised, tokens cannot be recovered.
  • AES-256-GCM encryption. Provider credentials are encrypted at rest using AES-256-GCM with per-project keys.
  • Scoped access. Each agent token can be restricted to specific providers, operations, and budget limits.

Architecture diagram

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
+------------------+         +--------------------+         +------------------+
|                  |         |                    |         |                  |
|   Your Agent     |  ks_    |   Keystore Proxy   |  sk-    |   OpenAI API     |
|   (SDK)          | ------> |   (Fly.io)         | ------> |   (Provider)     |
|                  |         |                    |         |                  |
+------------------+         +--------------------+         +------------------+
                             |                    |
                             |  - Token validation|
                             |  - Scope checking  |
                             |  - Key decryption  |
                             |  - Rate limiting   |
                             |  - Cost tracking   |
                             +--------------------+
                                      |
                             +--------------------+
                             |   Neon Postgres    |
                             |   (Encrypted keys) |
                             +--------------------+

Next steps

Previous
← Installation
Next
BYOK vs Marketplace →