# 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](https://docs.atlas.ilionx.dev/concepts/api-keys.md). For tasks, see [Create and manage your API keys](https://docs.atlas.ilionx.dev/guides/user/api-keys-create-and-manage.md) and [Monitor and revoke API keys](https://docs.atlas.ilionx.dev/guides/admin/api-keys-monitor-and-revoke.md).

## 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](https://docs.atlas.ilionx.dev/reference/roles-and-permissions.md))                         |

## 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](https://docs.atlas.ilionx.dev/guides/user/api-keys-connect-your-tools.md).

## 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](https://docs.atlas.ilionx.dev/reference/errors.md#common-gateway-codes).

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 `401` never 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](https://docs.atlas.ilionx.dev/reference/errors.md) and [Gateway](https://docs.atlas.ilionx.dev/reference/gateway.md).

## Related

- [Gateway reference](https://docs.atlas.ilionx.dev/reference/gateway.md)
- [Errors](https://docs.atlas.ilionx.dev/reference/errors.md)
- [Roles and permissions](https://docs.atlas.ilionx.dev/reference/roles-and-permissions.md)
- [Budgets](https://docs.atlas.ilionx.dev/reference/budgets.md)
- [Reference index](https://docs.atlas.ilionx.dev/reference.md)