What's in the session token

Atlas issues a short-lived RS256 session JWT (__session) that your backend verifies locally against Atlas's JWKS — no network call per request. This is the token a relying party trusts to identify the user.

How to verify it

• JWKS: https://<your-fapi-host>/.well-known/jwks.json

• Issuer (`iss`): https://<your-fapi-host> (your custom FAPI host once live, else the Atlas host)

• Algorithm: RS256 only — pin algorithms: ['RS256'].

• Lifetime: the access token is deliberately short (jwtTtlSeconds, default 60s) and refreshed via tokenStrategy: refresh. Allow a few seconds of clock tolerance; refresh the token rather than widening exp acceptance.

Standard claims

Conditional claims

• `email` / `email_verified` — present when auth_config.session.includeEmailClaim is on (default ON). Relying parties provision on first login from this; if you turn it off, read email_addresses from the BAPI user object instead.

• Custom claims — public_metadata you set on the user (and, on the portable-self surface, progression / tier / flair) are projected into top-level session claims. See the host-side contract for the projection rules.

What a relying party does

1. Read the __session cookie (parent-scoped to your registrable domain — see Cookies across your subdomains).

2. Verify signature + iss + exp against JWKS.

3. Provision/link the local user by sub (+ email on first login).

4. On expiry, refresh rather than re-authenticating.

Confirm the whole chain with the login-readiness probe.