Instance config: auth_config.session

Written for: ＋ Written for
Deprecated: ＋ Deprecated
Applies to: ＋ Applies to

AdminUpdated Sep 14, 2026

An instance's behaviour is driven by auth_config, read and written with PATCH /v1/instance (BAPI, sk_). Note the casing seam: `auth_config` keys are camelCase, while the rest of the BAPI is snake_case. This page documents the session block — the settings that most often decide whether a custom-domain login works.

Setting a value

curl -X PATCH "https://<your-fapi-host>/v1/instance" \
  -H "Authorization: Bearer sk_live_…" \
  -H "content-type: application/json" \
  -d '{"auth_config":{"session":{"includeEmailClaim":true}}}'

A patch merges within a section — setting one toggle never resets the lifetimes next to it.

`auth_config.session`

Key (camelCase)	Default	Effect
`includeEmailClaim`	true	Put `email`/`email_verified` in the `__session` JWT so relying parties provision on first login. Turn off for a minimal token (then use the BAPI `email_addresses` field).
`crossSubdomainCookies`	true	Scope the session cookie to your registrable domain (`.acme.com`) so app and FAPI subdomains both receive it. Required for essentially every custom-domain setup; never applies to the shared Atlas host.
`jwtTtlSeconds`	`60`	Access-token lifetime. Short by design; refresh rather than lengthen.
`idleMs`	—	Rolling idle timeout — a session dies after this long with no activity (when `idleTimeout` is on).
`absoluteMs`	7d	Hard cap on session age regardless of activity.
`multiSession`	`true`	Allow multiple concurrent sessions per user (account switcher).
`maxConcurrentSessions`	`0`	Cap concurrent sessions (0 = unlimited).
`tokenStrategy`	`refresh`	`refresh` = short access token + rotating refresh token.
`refreshRotation`	`true`	Rotate the refresh token on each use.
`idleTimeout`	`true`	Enforce the rolling idle window.
`rememberMe`	`false`	Offer a "remember this device" longer-lived option.
`revokeOnPasswordChange`	`true`	Kill existing sessions when the password changes.

Recommended for custom domains

includeEmailClaim: true and crossSubdomainCookies: true are the two that most often block a custom-domain login when off — both now default on. Verify with the login-readiness probe.

Was this page helpful?