Authentication
Bearer keys, what each one can do, and how to keep them contained.
Every request carries a key in the Authorization header:
Authorization: Bearer sk-cog-...| Prefix | sk-cog- |
| Header | Authorization: Bearer <key> |
Creating a key
Keys are created in the console. The full value is shown once, at creation, and never again; after that the console shows only the prefix. If you lose one, revoke it and create another.
The console also shows the base URL to paste into your client, so the two values you need are on the same screen.
Scoping a key
A key can be limited, which is what makes it safe to hand one to a script or a teammate:
| Control | What it does |
|---|---|
| Model allowlist | The key can only call the models you list. |
| Monthly budget | Spend against the key stops at the figure you set. |
| Concurrency | Caps requests in flight for that key. |
| Retention | How long request metadata for that key is kept, where your plan allows choosing. |
Three habits that prevent most incidents: one key per project rather than one key for everything, a budget on every key that runs unattended, and revocation of any key you cannot account for.
What we store
Requests and responses are not logged as content. What is kept is the metadata needed to meter and audit usage: which key made the request, when, which model, how many tokens, and the outcome. The details, per plan, are in Privacy and retention.
Rotating a key
Create the replacement, deploy it, then revoke the old one. Both are valid during the overlap, which is why the order matters: revoking first takes your service down.
Errors
| Status | Body type | Meaning |
|---|---|---|
401 | virtual_key_required | No credential was sent. |
401 | access_not_found | The credential does not exist or has been revoked. |
403 | model_not_allowed | The key is not scoped to the model you asked for. |
429 | rate_limit_exceeded | Concurrency or budget ceiling reached. |
Error bodies carry a machine-readable type, a status_code and a human message. The full list
with remedies is in Errors.