API keys reference#
Look up the format, acting context, validation rules, permissions and refusal checks for ATLAS API keys. For how keys relate to spaces, projects and budgets, see API keys concepts. For tasks, see Create and manage your API keys and Monitor and revoke API keys.
Key types and format#
| Type | Starts with | Length | Owner | Created in |
|---|---|---|---|---|
| Personal key | atl_sk_ |
39 characters (prefix and 32 letters or digits) | The person who created it | My API keys in the web app |
| Project key | atl_pk_ |
39 characters (prefix and 32 letters or digits) | A project, so it survives staff changes | The project's API keys tab |
- The web app shows only the last 4 characters of a key (
••••xxxx). - The creation dialog shows the full key once. Until the key expires, its owner can copy a personal key again with Copy Key. Admins and Owners can reveal a project key with Reveal secret….
- Revoking a key is permanent. Admins keep a record of the key, its owner, and who revoked it and when.
- A personal key name must be unique among your own keys, whichever space they act under. A project key name must be unique within its project.
Acting context#
A personal key acts under at most one context at a time. The context decides the models, budget and audit attribution of every request.
| Context | Meaning |
|---|---|
| Space | A Team space. Requests use the space's models and budget. |
| Project | An active project. Requests use the project's model list and funding. |
| None | The key signs in, but the gateway refuses every request with no_acting_context. |
The same context rules apply when you create a key and when you switch its context:
- Governance spaces (Divisions and Units) and the root Organisation space cannot be a context. Only Team spaces can.
- You must be an explicit member of the space or project. Owners and Admins are not exempt.
- A project must be Active.
- A key may act under a space or a project, but not both.
- Only the key's owner can switch or clear the context.
- Removing someone from a space or project clears the context of their keys that used it. The keys themselves are kept.
- Deleting a space or project clears the context of the keys that used it.
Project keys always act under their own project.
Expiry and validation#
| Rule | Message shown |
|---|---|
| Name required | The API key name is required. |
| Name length | At most 100 characters |
| Expiry in the past | The expiry date must not be in the past. |
| Space and project together | A key may act under a space or a project, but not both at the same time. |
| Space enforces a maximum validity: no expiry set | An expiry date is required: this space enforces a maximum API key validity period. |
| Space enforces a maximum validity: expiry too far away | The expiry date exceeds the space's maximum allowed API key validity period. |
| Name already used | Conflict (409). ERR-0037 for a personal key you own, ERR-0086 for a key in the same project. |
- The maximum validity is an organisation-wide policy, set on the root space. It applies only when a key acts under a space.
- Keys acting under a project, and keys with no context, have no cap and an optional expiry.
- ATLAS checks the cap only when you create a key. Switching a key's context never changes or re-checks its expiry, so a key keeps its expiry even if the new space has a stricter cap.
What you can do with a key#
| Action | Who |
|---|---|
| Create, switch context, reveal, revoke (own) | The owner |
| Revoke any key in the organisation | Admins and Owners |
| See the keys that act in a space | Space members see their own. Admins see all. Read only. Revoke from the organisation's keys page. |
| Search keys and see counters and the revocation history | Admins and Owners |
| Create and revoke a project's keys | Project managers, Account Managers, Admins and Owners |
| Reveal a project's key | Admins and Owners (see Roles and permissions) |
In the web app#
Status labels#
| Status | Rule |
|---|---|
| Active | Not expired and more than 7 days from expiry |
| Expiring Soon | Expires within 7 days (amber) |
| Expired | Past its expiry date (red) |
| Never expires | No expiry date set |
- Timestamps are shown in UTC, 24-hour.
- A key is usable when it has a context, its project (if any) is not archived and it has not expired. Otherwise the page shows why: unbound, archived or expired.
- Request counts and the last-used time can lag by up to about a minute.
Expiry choices when creating a key#
| Option | Notes |
|---|---|
| 7, 30, 90 (default), 180, 365 days | Presets |
| Custom | A date picker. You see an error if the date is over the space's cap. |
| Never | Hidden when you select a space that enforces a maximum validity. |
On your personal page, the limit shown is the lowest maximum validity across the spaces you can access.
Connect your tools#
The Connect your tools panel shows ready-to-copy settings for your own key.
| Item | Value |
|---|---|
| Anthropic base address | https://<atlas-host>/gateway/anthropic |
| OpenAI base address | https://<atlas-host>/gateway/openai/v1 |
| Key when it is not revealed | <your-atlas-key> |
| Claude Code settings | ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN and the model settings ANTHROPIC_DEFAULT_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL |
opencode baseURL |
The OpenAI address for OpenAI-compatible models. The Anthropic address followed by /v1 for Claude models. |
| Model tiers | Fable, Opus, Sonnet and Haiku are picked by model name. The fallback order is Fable, Opus, Sonnet, then the first Claude model. |
Only Claude models are offered for Anthropic settings. Claude models reached through an OpenAI-compatible provider are not eligible. For the steps, see Connect Claude Code and opencode.
How changes take effect#
Access changes reach the gateway within seconds. Request counts and last-used time are a separate matter. They update about once a minute.
| Change | Effect |
|---|---|
| Revoking a key | The key stops authenticating |
| Switching a key's context | The new context applies |
| Removing a member from a space or project | Their keys lose that context |
| Suspending the organisation | Requests are refused |
Expiry is checked on every request. For a few seconds after a change, a request may still run and be recorded under the previous context.
Why the gateway refuses a key#
Every gateway call needs a key, written here as <your-atlas-key>. The OpenAI addresses accept Authorization: Bearer <your-atlas-key> only. The Anthropic addresses also accept x-api-key: <your-atlas-key>. For the code meanings, see Errors.
Checks run in this order.
| Order | Check | Result |
|---|---|---|
| 1 | The key is present, well-formed and known | 401 authentication_required |
| 2 | The key has not expired | 401 authentication_required |
| 3 | A personal key's owner exists and is active | 401 authentication_required |
| 4 | The organisation is not suspended | 403 organization_suspended |
| 5 | If acting under a project, the project is not archived | 403 project_archived |
| 6 | The key has a space or project context | 403 no_acting_context |
- A
401never says why, so a key cannot be probed. Check the key's status on the My API keys page. - Requests with an invalid key aren't recorded. Refusals at steps 4 to 6 are recorded in the audit log.
- A valid key can still be refused for other reasons, such as an unavailable model or a used-up budget. See Errors and Gateway.