Quickstart

This walks the two most common first steps: managing users from your backend, and gating a request by a verified session.

1. Call the Backend API

Grab your secret key from the dashboard (API keys), then create and list users:

# Create a user
curl https://api.atlas.dev/v1/users \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-ada-001" \
  -d '{"email_address":"ada@example.com","first_name":"Ada"}'

# List users (one cursor page)
curl "https://api.atlas.dev/v1/users?limit=20" \
  -H "Authorization: Bearer sk_live_xxx"

With an SDK:

import { createAtlasClient } from '@atlas/backend';

const atlas = createAtlasClient({ secretKey: process.env.ATLAS_SECRET_KEY! });

const user = await atlas.users.create(
  { email_address: 'ada@example.com', first_name: 'Ada' },
  'signup-ada-001', // Idempotency-Key
);

const page = await atlas.users.list({ limit: 20 });
console.log(page.data, page.has_more, page.next_cursor);

2. Verify a session on your API

Your frontend sends the Atlas session JWT to your API. Verify it locally against your instance's JWKS — fast, offline, correct within the token lifetime:

import { AtlasBackend } from '@atlas/backend';

const atlas = new AtlasBackend({
  jwksUrl: 'https://accounts.yourapp.com/.well-known/jwks.json',
  issuer: 'https://accounts.yourapp.com',
});

const auth = await atlas.authenticateRequest(req);
if (!auth.ok) return res.status(401).end();

// Gate the action by a permission (throws ForbiddenError if unmet)
auth.protect({ permission: 'org:billing:manage' });

For the rare request where "signed out a moment ago" must mean now, call the authoritative check POST /v1/tokens/verify, which consults the revocation set. See Token verification.

3. Mount a frontend

// React
import { AtlasProvider } from '@atlas/react';

<AtlasProvider publishableKey="pk_live_xxx">
  <App />
</AtlasProvider>

Next: read Authentication for the full key model, then jump to the Backend API overview or the SDKs.