Docs/Concepts/Agent Tokens

Agent Tokens

How Keystore agent tokens work — the ks_ prefix convention, SHA-256 hashing, provider scoping, budgets, and rate limits.

Agent Tokens

Agent tokens are the core authentication mechanism in Keystore. They replace real API keys in your agent code. A token looks like this:

1
ks_3a7f2b9c1d4e8f0a6b5c9d2e7f1a4b8c3d6e9f0a2b5c8d1e4f7a0b3c6d9e2f5a

Format

Every agent token follows the same format:

  • Prefix: ks_ — identifies it as a Keystore token
  • Body: 64 hexadecimal characters — 32 bytes of cryptographically random data

The ks_ prefix makes tokens easy to identify in code reviews, secret scanners, and log monitoring. If a ks_ token accidentally leaks, it cannot be used to access provider APIs directly — it only works through the Keystore proxy.

How tokens are stored

Keystore never stores the raw token. When you create an agent token:

  1. The system generates 32 bytes of random data and hex-encodes it
  2. The full token (ks_ + hex) is shown to you once
  3. A SHA-256 hash of the token is computed and stored in the database
  4. The raw token is discarded from server memory

When your agent sends a request with a ks_ token, the proxy hashes it and looks up the hash. This means:

  • If the database is compromised, attackers get hashes, not usable tokens
  • Tokens cannot be recovered or regenerated — if lost, create a new one
  • Token comparison is constant-time to prevent timing attacks

Scoping

Each agent token can be scoped to control what it is allowed to do.

Provider scopes

Restrict which providers the token can access:

1
2
3
4
5
6
provider:openai:read
provider:openai:write
provider:anthropic:read
provider:anthropic:write
provider:neon:read
provider:neon:write

A token scoped to provider:openai:* can call any OpenAI endpoint but will be rejected if it tries to access Anthropic or Resend.

Wildcard access

A token with no explicit scopes can access all providers configured in the project. This is convenient for development but not recommended for production agents.

Budgets

You can set spending limits on agent tokens to prevent runaway costs:

  • Per-request limit — Maximum estimated cost for a single API call
  • Daily limit — Maximum total spend in a 24-hour window
  • Monthly limit — Maximum total spend in a calendar month
  • Lifetime limit — Maximum total spend over the token's entire lifetime

When a budget threshold is reached, the proxy rejects the request with a 429 status code and a clear error message indicating which limit was hit.

Cost estimation is based on provider pricing for the specific API endpoint and request parameters (e.g., token count for LLM calls, email count for Resend).

Rate limits

Independent of budgets, you can configure rate limits per token:

  • Requests per minute — Maximum number of API calls per minute
  • Requests per hour — Maximum number of API calls per hour
  • Requests per day — Maximum number of API calls per day

Rate limits are enforced at the proxy using Upstash Redis for distributed counting. When a limit is exceeded, the proxy returns a 429 response with a Retry-After header.

Token lifecycle

Creating tokens

Tokens are created through the dashboard or the API. You can set:

  • A human-readable name (e.g., "production-agent", "dev-testing")
  • Provider scopes
  • Budget limits
  • Rate limits
  • An optional expiration date

Revoking tokens

Tokens can be revoked instantly from the dashboard. Revocation takes effect immediately — the next request with that token will be rejected. There is no way to un-revoke a token; create a new one instead.

Rotating tokens

To rotate a token:

  1. Create a new token with the same scopes and limits
  2. Update your agent code to use the new token
  3. Revoke the old token

Keystore does not support in-place rotation because the raw token is never stored.

Best practices

  • One token per agent. This gives you per-agent visibility into usage, costs, and rate limiting.
  • Scope tokens to the providers they need. Do not give an email-sending agent access to your database.
  • Set budget limits in production. A bug in your agent should not drain your OpenAI account.
  • Set expiration dates for temporary access. If you are giving a contractor's agent access, set the token to expire when the contract ends.
  • Never log agent tokens. Treat ks_ tokens like passwords — they grant access to real API credentials through the proxy.

Next steps

Previous
← BYOK vs Marketplace
Next
TypeScript SDK →