Add Atlas to your app — a guide for AI agents

Audience: the AI coding agent wiring Atlas into an existing website or app. Goal — add complete authentication (sign-up, sign-in, sessions, organizations, roles) end to end, from one page you can execute top to bottom. Everything below is copy-pasteable; swap the placeholders and go.

• Full API reference (every route): https://developers.atlasauth.net

• Guides: https://docs.atlasauth.net

• Dashboard: https://atlasauth.net/dashboard

Facts you'll reuse

• Two keys per instance. Publishable pk_… (client/browser — safe to ship) and secret sk_… (server only — never ship to the browser, never commit). Both are in the dashboard under your application → API keys.

• Two API surfaces. The Frontend API (FAPI) is browser-facing and authenticated by the publishable key; the Backend API (BAPI) is server-facing and authenticated by Authorization: Bearer sk_…. You rarely call these directly — the SDKs do it for you.

• Sessions are JWTs. After sign-in, Atlas issues a short-lived session JWT (rotated automatically). Your backend verifies it locally against the instance's JWKS — no network round-trip per request.

• Dev vs prod. Every application has a development and a production instance, each with its own keys and its own users. Build against dev; switch the keys for prod.

• Base URL. The SDKs default to your instance's API origin; you only set the keys. For raw REST, the base + exact paths are on the API reference.

1. Create an application + grab keys

1. Sign in at https://atlasauth.net/dashboard and create an application (or open an existing one).

2. Open API keys. Copy the publishable key (pk_test_… in dev) and the secret key (sk_test_…).

3. Put them in the app's env — publishable in the client/build env, secret on the server only:

   # .env  (server)          .env.local / build env (client)
   ATLAS_SECRET_KEY=sk_test_…  NEXT_PUBLIC_ATLAS_PUBLISHABLE_KEY=pk_test_…

   (Prefix the publishable key however your framework exposes client env — NEXT_PUBLIC_, VITE_, PUBLIC_, EXPO_PUBLIC_, …)

2. Pick the SDK for the stack

Atlas ships first-party SDKs across every major stack — install the one that matches:

Rule of thumb: a frontend/mobile SDK (publishable key) renders sign-in and holds the session; a backend SDK (secret key) verifies sessions and calls the management API.

3. Frontend — mount sign-in

Wrap the app in the provider (publishable key), then drop in the prebuilt components. React/Next example:

// app providers
import { AtlasProvider, SignedIn, SignedOut, SignIn, UserButton } from '@atlas/react';

<AtlasProvider publishableKey={process.env.NEXT_PUBLIC_ATLAS_PUBLISHABLE_KEY!}>
  <SignedOut><SignIn /></SignedOut>
  <SignedIn><UserButton /> {/* your app */}</SignedIn>
</AtlasProvider>

Same shape in every framework: createAtlas({ publishableKey }) (Vue plugin / Nuxt module / Angular provideAtlas / Svelte initAtlas), then <SignedIn>/<SignedOut>/<SignIn> and a useUser() / useSession() accessor. Which sign-in methods appear (password, email/SMS code, magic link, social, passkeys) is controlled in the dashboard, not in code — see Sign-in methods.

4. Protect a route

Client-side (hide UI):

const { isSignedIn } = useAuth();
if (!isSignedIn) return <SignIn />;

At the edge (Next.js middleware — bounce anonymous users before render):

// middleware.ts
import { atlasMiddleware } from '@atlas/nextjs/server';
export default atlasMiddleware({ protect: ['/dashboard(.*)'] });

On the server (see §5) is the real enforcement — client/edge checks are UX, the backend verify is the security boundary.

5. Backend — verify the session

The frontend sends the session JWT (Authorization header or the __session cookie). Verify it locally with the backend SDK + your secret key:

import { createAtlasClient } from '@atlas/backend';
const atlas = createAtlasClient(process.env.ATLAS_SECRET_KEY!);

// in a request handler:
const auth = await atlas.authenticateRequest(req);   // reads header/cookie, verifies JWT vs JWKS
if (!auth.isSignedIn) return res.status(401).end();
const userId = auth.userId;                            // trust this

Every backend SDK exposes the same: authenticateRequest(req) / verifyToken(token) returning the verified claims (userId, sessionId, orgId, roles). It's local + cached, so it's cheap per request. Call the management API through the same client — e.g. atlas.users.get(userId), atlas.organizations.list(). Full surface: https://developers.atlasauth.net

6. Organizations, roles & permissions

If the app is multi-tenant, use organizations + RBAC. Check permissions on the verified claims — never trust the client:

if (!auth.has({ permission: 'org:billing:manage' })) return res.status(403).end();
// or by role:
if (!auth.has({ role: 'admin' })) return res.status(403).end();

Create/manage orgs, members, roles and invitations from the dashboard or the backend SDK (atlas.organizations.*). See Organizations & teams.

7. Webhooks — react to events

To sync users/orgs into your own DB, subscribe to webhooks (dashboard → Webhooks, or the API). Atlas signs each delivery — always verify the signature over the raw body before trusting it:

• Headers: atlas-id, atlas-timestamp, atlas-signature (v1,<base64 HMAC-SHA256(secret, "id.timestamp.body")>).

• Reject if the timestamp is older than ~5 minutes (replay protection).

import { verifyWebhook } from '@atlas/backend';
const evt = verifyWebhook(rawBody, req.headers, process.env.ATLAS_WEBHOOK_SECRET!); // throws if invalid
// evt.type e.g. 'user.created', 'session.revoked', 'organization.membership.created'

Event catalog + payloads: https://developers.atlasauth.net (Webhooks).

8. Go to production

1. In the dashboard switch to the application's production instance; copy its pk_live_… / sk_live_….

2. Set the production keys in your prod env (publishable in the client build, secret on the server).

3. (Optional) Point auth pages at your own domain and customize branding — see Customization.

4. Set the webhook endpoint's production URL + secret.

Prefer not to hand-roll? Use the MCP server

Atlas ships an MCP server (@atlas/mcp) exposing the same read/manage surface as typed tools — so an agent can create apps, read users/orgs, and configure the instance without hand-writing REST calls. Point your MCP client at it with a scoped key.

Checklist

1. Application created; pk_/sk_ copied — publishable in the client env, secret server-only.

2. SDK for the stack installed; provider mounted with the publishable key.

3. Sign-in renders (<SignIn/> / <SignedIn>/<SignedOut>).

4. Routes protected — client/edge for UX, backend authenticateRequest for enforcement.

5. Permissions checked with auth.has({ permission | role }) on verified claims.

6. Webhooks subscribed + signature verified over the raw body.

7. Production instance keys swapped for launch.

Full reference: https://developers.atlasauth.net · Guides: https://docs.atlasauth.net