Authentication

Every Atlas surface authenticates differently, because each has a different trust boundary. Pick the credential that matches the surface you are calling.

API keys

Your instance issues two kinds of key. They are not interchangeable.

The _live_ / _test_ segment selects the environment. A publishable key identifies your instance to the Frontend API; the SDKs derive the FAPI host from it (or you pass frontendApi explicitly). A secret key carries full administrative power over the instance — treat it like a password, keep it out of source control, and rotate it if it leaks.

Backend API (BAPI) — secret key

Server-to-server calls use the secret key as a bearer token:

curl https://api.atlas.dev/v1/users \
  -H "Authorization: Bearer sk_live_xxx"

The key is never placed in a URL and never logged. A missing or malformed key is 401 UNAUTHENTICATED; a revoked or wrong key is 401 INVALID_KEY. A valid key that lacks the scope a route requires is 403 SCOPE_MISSING with meta.required_scope.

Scopes

Secret keys are scoped. Each BAPI route declares the scope it needs — for example users:read, users:write, organizations:write, webhooks:write, sessions:read. Mint a key with only the scopes an integration needs. Every endpoint in this reference lists its required scope.

Frontend API (FAPI) — publishable key + session

Browser and native clients call FAPI with the publishable key and (once signed in) the Atlas session:

curl "https://<instance>.fapi.atlasauth.net/v1/client" \
  -H "x-publishable-key: pk_live_xxx"

• On the web, the session travels as an HttpOnly cookie set by Atlas; the SDK also mints short-lived session JWTs for your own API.

• On native, there is no cookie jar — the SDK stores the session token and sends it as a bearer header.

• GET /v1/client boots the client and returns session: null for a signed-out visitor (never 401).

Personal access tokens (uat_)

A signed-in user can mint a scoped personal access token (POST /v1/client/me/api_tokens) so an agent or script can drive their own account over the me-surface with a bearer header. These are session-only, scoped, and the secret is shown exactly once.

Standards-based surfaces

• OIDC / OAuth2 clients authenticate at /oauth2/token with client_secret_basic, client_secret_post, or PKCE (public clients). Access tokens are bearer tokens accepted at /oauth2/userinfo and your own resource servers.

• SCIM directory sync authenticates with a per-organization SCIM bearer token (minted via POST /v1/scim_tokens, shown once).

• Webhooks are the reverse direction: Atlas signs each delivery so you can authenticate it — see Verifying webhooks.

End-user API keys (ak_)

Distinct from your instance keys: a tenant can mint API keys for its own users/organizations (POST /v1/api_keys, returns an ak_ secret once) and later verify a presented one with POST /v1/api_keys/verify. See End-user API keys.