Docs / Guides
Securing API keys
Set spending limits and allowlists on each key, watch key activity, and replace or revoke a key.
Last updated
Your setup
Fills in YOUR_API_KEY in the code on this page. The key stays in this tab: it is never sent and never saved.
How keys are stored
An API key looks like cai_<secret>. The secret is random, 256 bits. Cent AI shows the full key once, when you create it, and then stores only a SHA-256 hash. Nobody can read the key back from the dashboard or the API, including Cent AI. The key list shows only a short hint such as cai_k3F9aQ.
If you lose a key, create a new one.
New keys have no limits
A new key has no limits. Anyone who has a key without limits can spend your whole balance. The dashboard warns you when you create a key without a limit; it does not block you.
Give each key the smallest limits it needs. Use one key per app, device or environment, so you can limit and revoke them one at a time.
Limits on a key
Set these in Keys when you create a key, or edit them later. All are optional.
| Setting | What it does | When it is not met |
|---|---|---|
| Daily limit | Maximum spend per day in USD | 429 key_limit_exceeded |
| Monthly limit | Maximum spend per month in USD | 429 key_limit_exceeded |
| IP allowlist | Only these IP addresses or CIDR ranges can use the key | 403 ip_not_allowed |
| Model allowlist | Only these model IDs can be used with the key | 403 model_not_allowed |
An empty setting means no limit for that setting.
Spending limits use UTC periods: a day starts at 00:00 UTC, and a month starts on its first day at 00:00 UTC. The 429 message says when the limit resets:
{"error": {"message": "This key reached its daily limit. Raise the limit or wait until 2026-10-28T00:00:00Z.", "type": "rate_limit_error", "param": null, "code": "key_limit_exceeded"}}
Limits are checked when a request starts. A request that is already running when the limit is reached finishes and is charged in full, so spending can go a little past a limit.
Every key also has a rate limit of 600 requests per minute, see Rate limits. A key's project can have its own budget on top of the key limits, see Projects and budgets.
Watch key activity
Each key has an activity log in Keys:
| Event | Meaning |
|---|---|
created | The key was created |
first_used | The key made its first request |
new_ip | The key was used from an IP address it has not used before |
limit_changed | A limit or allowlist on the key was changed |
revoked | The key was revoked |
A new_ip you do not recognise is a sign the key may have leaked.
Replace a key
Cent AI has no rotate button. To replace a key:
- Create a new key with the same limits and allowlists.
- Move your app to the new key and check that requests succeed.
- Revoke the old key.
The old key keeps working until you revoke it, so you can switch without downtime.
Revoke a key
Revoke a key in Keys. Revocation takes effect within seconds and cannot be undone. After that, requests with the key return HTTP 401 invalid_api_key, the same response as a wrong key.
If a key leaks: revoke it first, then create a replacement and check Requests and the key's activity for use you do not recognise.
Keep keys out of code and browsers
- Read the key from an environment variable or a secret store, not from source code.
- Do not put a key in frontend code. Model endpoints answer cross-origin requests, so anyone who opens the page can copy the key. Call Cent AI from your server, or give a browser key tight limits.
- Do not paste keys into issues, chats or screenshots.
export CENT_AI_KEY="YOUR_API_KEY"
Management keys
A management key cai_mgmt_<secret> only reads balance and usage through the Usage API. It cannot call models, and API keys cannot read the Usage API. It is also shown once and stored as a hash. Create and revoke management keys in Settings; revocation takes effect within seconds.