Skip to main content
All Build API calls go to https://mcp.atlaso.ai/developer/v1 and authenticate in one of two ways.

​
Mode A — project key + subject

The primary, server-to-server model. You send your project key and name the end-user you’re acting for:
  • Key format: atlk_ + a 12-character hex prefix + _ + a long random secret. Mint it in Settings → Developer → New key; it’s shown once.
  • Subject: any stable string you choose for one of your users or devices. Must match ^[A-Za-z0-9_.:@\-]{1,128}$. It’s case-sensitive and stored as-is.
The project key can address any subject in the project — so it must stay on your server (see below).

​
Mode B — per-device credential

For hardware you don’t fully control (an ESP32, a robot), mint a credential whose subject is baked in, so the device can’t address anyone else:
  • Format: atldev_ + a 12-character hex id + _ + a 32-character hex secret (128-bit).
  • The subject is pinned to the credential. Sending an X-Atlaso-Subject header alongside a device bearer is rejected with 400 — the credential already decides the subject.
  • A device credential can only remember, recall, and delete its own subject’s memories. It can never mint other credentials or create projects.
Mint, batch-enroll, and revoke device credentials from your backend — see Devices & hardware.

​
Keeping keys safe

A project key (atlk_…) is a bearer secret. Anyone holding it can read and write every subject in the project. Keep it server-side — never ship it in a browser bundle, a mobile app, or on device flash. For devices, use a per-device atldev_ credential instead.
The X-Atlaso-Subject header is a claim, not a login — Atlaso trusts that your server already authenticated the end-user before it set the subject. Do your own auth first, then call Atlaso.

​
Errors

Failures are fail-closed and return JSON. Authentication and entitlement failures include an X-Atlaso-Error header naming the cause; some validation 400 and 422 responses use FastAPI’s standard error shape and omit that header.
A lapsed Build subscription returns 402 on the data plane but keeps your keys and memories intact, and you can still list and revoke keys — so you can wind down or kill a leaked key even while unsubscribed. Renew and everything resumes.