Sessions & JWTs

When a user finishes signing in, Atlas creates a session. The session is represented by a short-lived, signed JWT that travels with each request, plus a longer-lived refresh mechanism that keeps the user signed in.

The session lifecycle

1. Created — after a successful sign-in (and MFA, if required). Atlas issues a session and its first token.

2. Active — the session token is presented on requests. It's short-lived (minutes), so a stolen token expires quickly.

3. Refreshed — before the token expires, the SDK silently exchanges the session for a fresh token. Atlas performs reuse detection: if an old token is replayed, the session is invalidated.

4. Ended — on sign-out, on revocation from the dashboard or Backend API, or when the session's maximum lifetime elapses.

Verifying a session on your backend

You have two options.

Stateless — verify the JWT against JWKS (recommended for scale)

Your instance publishes its public signing keys at:

/.well-known/jwks.json

Fetch and cache those keys, then verify the token's signature and claims (issuer, audience, expiry) locally. No network call to Atlas per request:

1. Read the session JWT from the request (cookie or Authorization header).
2. Verify its signature using the matching key from JWKS.
3. Check exp / nbf / iss / aud.
4. Trust the claims (user id, org id, roles) inside.

Stateful — ask the Backend API

Call the Backend API with your secret key to check a session or fetch the current user. Slightly heavier, but always reflects the very latest revocation state.

What's inside the token

A session JWT carries standard claims plus Atlas claims: the user id, the active organization id (if any), and — when you enable them — roles, permissions and any custom claims you configure. That means your services can make authorization decisions straight from the verified token. See Roles & permissions.

Session security controls

From Security → Sessions you can tune:

• Token lifetime and maximum session lifetime.

• Inactivity timeout (sign out idle users).

• Single-session mode (a new sign-in ends older ones).

• Global revoke all sessions for an incident.

See Session security for guidance.

Next

Now that you know who the user is, decide what they may do → Authentication vs authorization.