# API keys

An API key is the credential a person, tool or pipeline presents to the ATLAS gateway. It authenticates the caller and decides **who is charged and audited**. The key's _acting context_ is a team space or a project. It determines which models, budget and audit trail a request uses.

## Two kinds of key

- **Personal keys** belong to one user. They act under one team space or one project that the owner chooses. The owner can move them between contexts without changing the secret.
- **Project keys** belong to a project, not a person, so they survive staff changes. They always act under their project. For more information, see [Projects](https://docs.atlas.ilionx.dev/concepts/projects.md).

```mermaid
flowchart LR
    U[User] -- owns --> K[Personal key]
    P[Project] -- owns --> PK[Project key]
    K -- acts under --> C{One context}
    C --> S[Team space]
    C --> PR[Active project]
    C --> N[None: requests rejected]
    PK -- always acts under --> P
    S & PR --> M[Models, budget, audit attribution]
```

- A key never acts under both a space and a project.
- A key with no context still authenticates, but ATLAS rejects every request. This makes it safe to park a key.
- Only team spaces can host keys. Divisions, units and the organisation root can't.

## Why the context lives on the key

Developers use one tool for several pieces of work. The context lives on the key, not on each request. So IDEs and command-line tools stay unchanged: they send the same secret, and the owner chooses in ATLAS which budget it draws on. Switching context updates the key. It isn't a new credential. Rotating a key is separate: revoke it and create a new one.

Membership is the gate. You can only point a key at a space or project you are an explicit member of. Owners and Admins can manage every space without a membership. To act through a key, they still need membership like everyone else. A key can never spend a budget its owner couldn't otherwise use. If the membership is removed, the key stays but becomes unbound.

## Lifecycle

```mermaid
stateDiagram-v2
    [*] --> Active: create (dialog shows secret)
    Active --> Active: switch context
    Active --> Unbound: removed from space or project, or it is deleted
    Unbound --> Active: owner picks a new context
    Active --> Expired: expiry date passes
    Active --> Revoked: owner or Admin revokes
    Unbound --> Revoked
    Expired --> Revoked
    Revoked --> [*]
```

- **Creation** takes a name, an optional context and an optional expiry date. The creation dialog shows the secret once. Copy it straight away.
- **Expiry** is optional unless your organisation caps key lifetime. The rules are in the [API keys reference](https://docs.atlas.ilionx.dev/reference/api-keys.md#expiry-and-validation).
- **Revocation** is permanent. ATLAS keeps a record of the revoked key for the audit trail: its context, owner, request total and who revoked it.
- **Copying the secret again** works differently for the two kinds of key. You can copy your own personal key with **Copy Key** in its row menu until it expires, so a lost key needs no rotation. Admins can't read your personal keys. A project's key is different: an Admin or Owner can reveal it from the project's key list, until it expires.

ATLAS stores keys encrypted. Lists and reports show only the last four characters.

## What callers see

- **Same answer for most failures.** A missing, wrong, revoked, expired or disabled-owner key returns the same "authentication required" answer. Nobody can probe which keys exist.
- **A different answer for a valid key that can't be used.** You get a specific message if the organisation is suspended, the project is archived or the key has no context. It tells you to contact an Admin or choose a context.
- **Two ways to send the key.** OpenAI-compatible calls use an `Authorization: Bearer` header. Anthropic-compatible calls also accept `x-api-key`, which is what Anthropic SDKs and Claude Code send.
- **Usage counters** (request totals and last used) are batched, so they can lag by up to a minute. This is only about the numbers you see. It doesn't affect whether a key works.

## Changes take effect within seconds

These access changes reach the gateway within seconds:

- Revoking a key
- Switching its context
- Removing a member
- Suspending an organisation

Requests inside that window may be attributed to the previous context. The web app shows an "Applying context change…" notice after a switch. Scripts that call the API directly should expect the same short delay.

## Who can see and manage keys

```mermaid
flowchart TB
    O[Owner] -->|create, switch, revoke, copy| K((Key))
    SV[Space members] -->|view their own keys acting in the space| K
    OA[Admin] -->|search, review, revoke| K
```

- Owners manage their own keys. Space pages are read-only, so revocation happens in one place. Space members see only their own keys there. Admins and Owners see all of them.
- Admins and Owners see and revoke every key in the organisation, including project keys. They can also review the record of revoked keys.
- Project managers and Account Managers create and revoke project keys from the project page. They can't reveal a project key.
- Asking about a key you can't access looks the same as asking about one that doesn't exist.

## Related

- Concepts: [Budget and cost](https://docs.atlas.ilionx.dev/concepts/budget-and-cost.md), [Gateway](https://docs.atlas.ilionx.dev/concepts/gateway.md), [Spaces](https://docs.atlas.ilionx.dev/concepts/spaces.md), [Projects](https://docs.atlas.ilionx.dev/concepts/projects.md)
- Reference: [API keys](https://docs.atlas.ilionx.dev/reference/api-keys.md)
- Guides: [Create and manage your API keys](https://docs.atlas.ilionx.dev/guides/user/api-keys-create-and-manage.md), [Connect Claude Code and opencode](https://docs.atlas.ilionx.dev/guides/user/api-keys-connect-your-tools.md), [Monitor and revoke API keys](https://docs.atlas.ilionx.dev/guides/admin/api-keys-monitor-and-revoke.md)