Sessions & tokens (frontend)

On the client, the SDK manages the session for you — but the underlying FAPI endpoints are here for custom UIs and to understand what getToken() does.

The session lifecycle

GET  /v1/client                       → boot; session: null when signed out (never 401)
GET  /v1/client/sessions              → the user's own active sessions/devices (flags the current)
POST /v1/client/sessions/:id/touch    → switch the active organization (membership resolved server-side)
POST /v1/client/sessions/:id/tokens   → rotate the refresh token and mint a session JWT
POST /v1/client/sessions/:id/revoke   → revoke one session and clear its cookies
POST /v1/client/sessions/revoke_all   → sign out every OTHER device; bumps sessions_version

Getting a token for your own API

Your frontend calls your backend with a short-lived Atlas session JWT. The SDK's getToken() mints/refreshes it:

import { useAuth } from '@atlas/react';

const { getToken } = useAuth();

// Standard session JWT
const token = await getToken();
await fetch('/api/things', { headers: { Authorization: `Bearer ${token}` } });

Your backend then verifies it — see Session & JWT verification.

Template tokens

For a downstream that needs bespoke claims (Hasura, RLS, a partner API), mint a token from a named JWT template:

POST /v1/client/sessions/:id/tokens/:template   → mint a JWT for the active session using a named template

const hasuraToken = await getToken({ template: 'hasura' });

Token lifetimes

Session JWTs are short-lived (about 60 seconds) and rotated transparently by the SDK from the refresh token. This is what makes local JWKS verification safe: a revoked session stops working within one lifetime. For operations that cannot tolerate that window, verify authoritatively with POST /v1/tokens/verify.

CIBA (backchannel) approvals

For decoupled flows where approval happens on another device:

GET  /v1/client/me/backchannel_requests       → pending CIBA approval requests
POST /v1/client/me/backchannel_requests/:id    → approve or deny (session-only; a PAT cannot approve)