Docs menu

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.

SettingWhat it doesWhen it is not met
Daily limitMaximum spend per day in USD429 key_limit_exceeded
Monthly limitMaximum spend per month in USD429 key_limit_exceeded
IP allowlistOnly these IP addresses or CIDR ranges can use the key403 ip_not_allowed
Model allowlistOnly these model IDs can be used with the key403 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:

EventMeaning
createdThe key was created
first_usedThe key made its first request
new_ipThe key was used from an IP address it has not used before
limit_changedA limit or allowlist on the key was changed
revokedThe 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:

  1. Create a new key with the same limits and allowlists.
  2. Move your app to the new key and check that requests succeed.
  3. 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.