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
- something can pay for a request: an active plan, a positive wallet balance, an unexpired sign-up bonus, or a model that is free right now (see free models).
Without any of these, creating a key returns no_funding and points you to billing. With only a free model, the key works for the free models; requests to other models are refused until you buy a plan or top up.
The form asks for:
| Field | Required | What it does |
|---|---|---|
| Name | Yes | A label for you. Use where the key lives: "laptop", "github-actions", "support-bot". |
| Monthly spend cap (USD) | No | The most this key may spend in a calendar month. |
| Allowed models | No | The only model ids this key may call. Empty means every model your account can use. |
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 (choose "Stop at once") 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_exceededslightly 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/modelswith a restricted key lists only the allowed models.
Limits are fixed at creation
The spend cap and the allowed-models list can't be edited after the key is created. To change either, create a new key with the new limits, move your tools to it, then revoke the old one.
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
.envfile 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.
If a key leaks
Rotate or revoke it in /dashboard/keys immediately, then check usage for requests you don't recognise. Deleting a commit doesn't help: assume anything pushed to a remote has been copied.
Rotate an API key#
Rotation gives a key a new secret and keeps everything else about it: its name, spend cap, allowed models, usage history and the spend counted against its monthly cap.
When you click Rotate in /dashboard/keys, you choose what happens to the old secret:
| Choice | The old secret |
|---|---|
| Stop at once | Stops immediately. Use this when the key leaked. |
| Keep the old secret for 1 hour | Keeps working for one hour next to the new one, then stops. |
| Keep the old secret for 24 hours | Keeps working for 24 hours next to the new one, then stops. |
The new secret works the moment it is shown. While the old one still works, the key's row says "Old secret … still works until …" with the exact time. Once the old secret stops, any request that uses it gets 401 invalid_api_key; requests already running finish normally.
So rotate in this order:
- Pick "Keep the old secret for 1 hour" or "24 hours" (or "Stop at once" if the key leaked).
- Click Rotate and copy the new secret. It is shown once.
- Update every place that used the old one (env vars, CI secrets, agent configs) before the old secret stops.
A few rules:
- Both secrets are the same key. Requests with either one count towards the same spend cap, limits and usage.
- One old secret at a time. Rotating again while an old secret still works stops that older secret at once.
- Stop it early. Stop old secret now on the key's row ends the overlap immediately; the new secret keeps working.
- Deleting the key stops both secrets at once.
- An expiry date still applies. If an administrator gave the key an expiry date, the old secret never outlasts it, and an expired key can't be rotated.
Revoke an API key#
Revoking (Delete in the dashboard) disables a key permanently, effective immediately: its secret, and an old secret still in its overlap after a rotation, stop at once. 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.
A revoked key leaves your key list but not your history: requests it made stay in the activity on the usage page and in usage exports, named "key name (deleted)". A revoked key can't be restored; create a new one instead.
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.
Creating, rotating and deleting a key, and stopping an old secret early, each add a line to the Security Audit Log under your keys. Creating, rotating and deleting a key also send an email to your account's address that names the key by its prefix, never its secret (see security notices).
Key error codes#
Errors on the OpenAI-style endpoints come back in the OpenAI shape (on /v1/messages they use Anthropic's, see Errors), 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": "..."
}
}| HTTP | Code | Meaning | What to do |
|---|---|---|---|
| 401 | missing_api_key | No Authorization or x-api-key header | Check the variable is set in the shell that runs your tool |
| 401 | invalid_api_key | The key doesn't exist, was mistyped or deleted, or it is a rotated key's old secret that has stopped | Copy the current secret, or create a new key |
| 403 | key_inactive | The key is no longer active (for example, suspended) | Use another key, or ask support why it was suspended |
| 403 | key_expired | The key was provisioned by an administrator with an expiry date, and that date has passed | Create a new key |
| 403 | model_not_allowed_on_key | The model isn't on this key's allowed list; the message lists the allowed ones | Use an allowed model, or create a key that includes this one |
| 403 | monthly_spend_cap_exceeded | This key has hit its monthly cap | Wait for the next calendar month, or create a key with a higher cap |
| 403 | account_suspended | The whole account is suspended | Contact support |
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.