Docs menu

Docs / Get started

Authentication

Send your API key as a Bearer token or in the x-api-key header.

Last updated


API keys

An API key looks like cai_<secret>. You create keys in Keys in the dashboard. The full key is shown once when you create it; Cent AI stores only a hash.

Send the key in either header. Both are accepted on every model endpoint.

HeaderTypical use
Authorization: Bearer cai_<secret>OpenAI SDKs and tools, /v1/chat/completions, /v1/responses, /v1/models
x-api-key: cai_<secret>Anthropic SDKs and tools, /v1/messages
curl https://api.cent-ai.dev/v1/models \
  -H "Authorization: Bearer $CENT_AI_KEY"

If you send both headers with different keys, the header native to the protocol is tried first: x-api-key on /v1/messages, Authorization: Bearer elsewhere. If that key is not valid, the other header is tried. The request is billed to the key that was used.

Invalid keys

A wrong key, a revoked key and a key of a blocked account all return the same response, HTTP 401 invalid_api_key:

{"error": {"message": "Invalid API key. Check the key or create a new one in the dashboard.", "type": "authentication_error", "param": null, "code": "invalid_api_key"}}

The key is checked before anything else, so a wrong key gets 401 even on an endpoint that is not available yet.

Limits on a key

Each key can have, all optional:

  • a daily limit and a monthly limit; over the limit, requests return 429 key_limit_exceeded
  • an IP allowlist; other addresses get 403 ip_not_allowed
  • a model allowlist; other models get 403 model_not_allowed

New keys have no limits. Anyone who has a key without limits can spend your whole balance. Limits are checked when a request starts, so requests already running can go past a limit.

Every key belongs to one project. A project can have its own daily or monthly budget; over it, the project's keys return 429 project_budget_exceeded. A key of an archived project returns 403 project_archived until you restore the project.

Replacing or revoking a key

To replace a key, create a new key, move your application to it, then revoke the old one. Revocation takes effect within seconds.

Management keys

A management key looks like cai_mgmt_<secret>. It only reads usage and balance data through /v1/organization/* and cannot call models. A management key on a model endpoint returns 401, and an API key on /v1/organization/* returns 401.

Keep keys out of the browser

The API answers cross-origin requests (Access-Control-Allow-Origin: *), so a key placed in frontend code works, and anyone who opens the page can read it. Call Cent AI from your server, or give a browser key tight limits.