Skip to content
ATLAS
 Docs
On this page

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.
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#

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.
  • 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#

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.