API keys & tokens

Your applications authenticate to Atlas with keys. Getting the key model right — which key goes where, and how narrowly it's scoped — is the difference between a tidy integration and a standing liability.

The two key types

• Publishable key (pk_test_… / pk_live_…) — identifies your instance to the Frontend API. Safe to ship in a browser or mobile app; it can only start authentication attempts.

• Secret key (sk_test_… / sk_live_…) — authenticates your backend to the Backend API to read and manage users, organizations, sessions and more. Never put it in client code.

The test/live middle segment ties a key to your Development or Production instance — they're not interchangeable.

Minting, rotating and revoking

Under Integrations → API keys for the instance:

• Mint a secret key — it's returned exactly once; store it in your secrets manager immediately.

• Rotate a key to replace it without downtime — mint the new one, deploy it, then retire the old.

• Revoke a key that's leaked or unused. The key stops working at once; its record is kept so the audit log can still name it.

Scopes

A secret key doesn't have to be all-powerful. Atlas keys carry scopes of the form resource:action, so a key can hold exactly the access a job needs:

users:read      users:write
sessions:read   sessions:write
organizations:read   organizations:write
webhooks:read   webhooks:write
audit:read      invitations:write   domains:write   …

• Least privilege. A key that only reads users gets users:read — not a wildcard.

• Destructive scopes are called out. users:delete isn't just another list item; the dashboard renders data-destroying scopes distinctly, because a read scope and a delete scope are a permission and a loaded gun.

• Unknown scopes are refused, not dropped. Ask for a scope Atlas doesn't recognize (say user:read instead of users:read) and the mint is rejected — so a typo can never silently produce a key that looks authorized and isn't.

• The wildcard * grants everything; use it sparingly and prefer explicit scopes.

Platform-level keys (for provisioning instances) live in a separate scope catalog (platform:apps:*, platform:secrets:write) and can never hold per-instance scopes — a credential of one tier only ever carries scopes of its own tier.

Checking access

The Backend API rejects any request whose key lacks the required scope, so scoping is enforced on every call, not just documented. Verify user session tokens (a different thing from your secret key) against JWKS as in Sessions & JWTs.

Next

See how it's all being used → Usage & analytics.