JWT templates & custom claims

Sometimes you need a token that isn't Atlas's standard session JWT — a token shaped exactly the way a third-party service expects, with the claims it reads. A JWT template is a named claims map you define once and mint on demand.

What a template is

A JWT template is stored in the instance's auth config and has:

• A name (for example supabase, hasura).

• A claims map — the claim keys the target service expects, filled from the user/session (their id, email, active organization, roles, metadata) plus any static values.

• A lifetime for the minted token.

You manage templates under Integrations → JWT templates, or over the Backend API.

Minting a token

From the frontend, the SDK's getToken({ template }) mints a short-lived JWT for the active session using the named template. Your app then sends that token to the downstream service, which verifies it against your instance's public keys (JWKS) — no shared secret needed.

// Frontend: get a token shaped for a specific service
const token = await atlas.session.getToken({ template: 'supabase' });

await fetch('https://db.example.com/rows', {
  headers: { Authorization: `Bearer ${token}` },
});

Custom claims in the session token

Separately from named templates, you can inject custom claims into the ordinary session token — plan tier, feature flags, a tenant setting — so your own services authorize straight from the verified session without a lookup. Roles and permissions already ride in the token for an active organization:

{
  "sub": "user_2a…",
  "org_id": "org_9f…",
  "org_role": "org:admin",
  "org_permissions": ["org:billing:manage"],
  "plan": "pro"
}

A claims change takes effect within one token lifetime — the same bound as session revocation.

Good practice

• Keep templates minimal — only the claims the target service actually reads.

• Never put a secret in a claim; JWTs are signed, not encrypted, and are readable by anyone holding them.

• Verify downstream against JWKS (/.well-known/jwks.json), checking issuer, audience and expiry — see Sessions & JWTs.

Next

Manage the keys your backend uses → API keys & tokens.