API keys

A Tokens API key authenticates every call to /v1. This page covers creating keys, the two limits you can put on them, storing them safely, rotating and revoking, and what each key-related error means.

Create an API key#

Open /dashboard/keys and create a key. Two things must be true first:

• your email address is verified, and
• you have an active plan or a positive wallet balance.

The form asks for:

The secret looks like tok_live_ followed by 48 hex characters. It is shown once, right after creation. Tokens stores only a hash, so nobody can show it to you again. If you lose it, rotate the key or create a new one.

Send it as either header:

curl https://tokens.bd/v1/models -H "Authorization: Bearer $TOKENS_API_KEY"
curl https://tokens.bd/v1/models -H "x-api-key: $TOKENS_API_KEY"

Set a monthly spend cap and allowed models#

If you only change one setting, make it the spend cap. Coding agents run long loops, and a cap turns a runaway session into an error instead of a bill.

• Monthly spend cap. Tokens adds up what the key has spent since the start of the calendar month. Before each request it also counts the most that request could cost, so a request that might push the key over the cap is refused with monthly_spend_cap_exceeded slightly before the exact figure is reached. If you leave the field blank and your plan defines a default cap, the key gets that default.
• Allowed models. Restrict a key to the models a tool actually needs. A CI job that runs one cheap model shouldn't be able to call an expensive one. GET /v1/models with a restricted key lists only the allowed models.

How many keys can I have?#

Each plan sets a maximum number of active keys; the default is 3, and pay-as-you-go accounts without a plan also default to 3. When you reach it, creating another returns key_limit_reached ("Your ... plan allows N active keys"). Revoke a key you no longer use, or move to a plan with a higher limit on pricing.

One key per tool or machine is a good habit. It makes the usage dashboard readable and lets you revoke one leaked key without breaking everything else.

Store API keys safely#

Treat a key like a password. It spends your money.

• Use an environment variable. All examples in these docs read TOKENS_API_KEY.
• For projects, use a .env file and ignore it in git:

TOKENS_API_KEY=tok_live_your_key

.env
.env.*

• In CI, store the key as a secret in your CI provider and expose it as an environment variable at run time.
• Never put a key in client-side code. Browser and mobile apps ship their source to users. Tokens doesn't support browser calls anyway (responses have no CORS headers), so put a small server or serverless function in between and keep the key there.
• Agent config files. Claude Code, OpenCode and Crush keep the key in their config files under your home directory. That's fine on your own machine, but don't commit those files to a dotfiles repository.

Rotate an API key#

Rotation replaces the secret and keeps everything else about the key: its name, spend cap, allowed models and usage history.

The old secret stops working immediately. There is no grace period. Any tool still using it gets 401 invalid_api_key on its next request. So rotate in this order:

1. Have the places that use the key ready to update (env vars, CI secrets, agent configs).
2. Click Rotate on the key and copy the new secret.
3. Update every place that used the old one.

If you can't afford a short outage, create a second key first, switch your tools to it, and then revoke the old one.

Revoke an API key#

Revoking disables a key permanently, effective immediately. Use it for keys you no longer need and for any key you think has leaked. Revoked keys no longer count towards your active-key limit.

Signing out of the Tokens CLI with logout only deletes the copy on your computer; the key itself stays valid until you revoke it here.

Key error codes#

All errors come back in the OpenAI shape, with a request_id you can quote to support:

{
  "error": {
    "message": "Model 'example/model' is not permitted on this API key. Permitted models: deepseek/deepseek-v4.1-flash.",
    "type": "permission_denied_error",
    "code": "model_not_allowed_on_key",
    "param": null,
    "request_id": "..."
  }
}

monthly_spend_cap_exceeded is about the key. If your plan or wallet has run out instead, you will see window_exhausted, insufficient_credits or tier_permission_denied; those are covered in plans, credits and wallet and errors.