Sessions & tokens

A first-party login is four calls that use two credentials. The first three — preflight, verify, exchange — run from your login page or service with your app login credential (X-Tenant-Id + alcs_… bearer). The fourth — minting the token — runs from your product backend with its API Access machine token (see Management API). Nothing here uses the hosted login page — that's a separate path documented in Sign in with authreads.

1. Preflight — POST /api/v1/auth/login/preflight
   Send { email, password }. The response is { otp_required, grant }. If otp_required is false, you already hold a one-time grant; if true, an email OTP has been sent and grant is null until you verify it.
2. Verify OTP — POST /api/v1/auth/login/verify-otp
   Only when otp_required was true. Send { email, code } (add remember_device: true to reduce future OTP prompts). The response returns the one-time grant.
3. Exchange — POST /api/v1/auth/session/exchange
   Trade the single-use grant for a durable session: { user, session_id, account_session_id, session_policy, session_activity_token, kind }. Store all of these in your server-side session. session_id is the bearer used by authenticated calls; account_session_id is a non-credential handle used to retain the current session during self-service revocation; session_policy and session_activity_token are the idle-timeout contract described below.
4. Mint an access token — POST /api/v1/auth/token
   From your product backend, authenticated with your API Access machine token (tokens:issue scope), send { session_id, app, workspace_id? } to mint a short-lived, EdDSA-signed access JWT scoped to that user and target app. Verify it on every request; re-mint it when it expires rather than lengthening its lifetime.

The access token is a compact JWT your product verifies against the JWKS (no call back to authreads). Its payload — the AccessClaims — carries both identity and the authorization your product enforces:

Before a sensitive action — changing a password, approving a payment — ask the user to prove themselves again without starting a new session. From your product backend (API Access machine token, sessions:reverify scope), call POST /api/v1/auth/session/reverify. It accepts a password, or an email-OTP request followed by a verify:

# Password re-check
{ "kind": "password", "session_id": "5b1e…", "password": "••••••••" }
# → { "status": "verified", "authenticated_at": "2026-07-28T10:12:00Z", "amr": ["pwd"] }

# Or email OTP: request, then verify
{ "kind": "email_otp_request", "session_id": "5b1e…" }
# → { "status": "challenge_sent" }
{ "kind": "email_otp_verify", "session_id": "5b1e…", "code": "123456" }
# → { "status": "verified", "authenticated_at": "…", "amr": ["otp"] }

Two narrower internal-plane calls operate directly on a session_id, for a backend that tracks its own direct sessions rather than going through the account-security endpoints above. From your product backend, with an API Access machine token:

{ "session_id": "5b1e2c40-…" }
# → { "valid": true, "user": { "id": "…", "email": "…" }, "expires_at": "2026-08-11T18:42:00Z" }
# → { "valid": false, "reason": "revoked" }  # or "expired" / "user_disabled" / …

{ "session_id": "5b1e2c40-…" }
# → { "message": "session invalidated" }

Every session carries a resolved idle timeout — how long it tolerates real human inactivity before authreads treats it as ended. session_policy.idle_timeout_minutes from the exchange step above is that resolved value; session_activity_token is a short, API-signed, session-bound token that carries it forward. Store it alongside session_id.

1. Send it on every activity-checked call
   Alongside x-session-id, send the current token as x-session-activity. GET /api/v1/auth/me validates it on every call; a missing, tampered, cross-session, wrong-tenant, idle, or absolute-expired token fails 401 with a problem+json code of session_activity_invalid, session_idle_timeout, or session_activity_expired.
2. Refresh it on genuine user activity — POST /api/v1/auth/session/activity
   Call this only when your frontend observes real pointer or keyboard input from the signed-in user, never on a timer, a background poll, or a token refresh — none of those count as activity, and refreshing on them defeats the idle timeout entirely. Send x-session-id and the current x-session-activity; store the token this returns in place of the old one:

   POST /api/v1/auth/session/activity

   curl -X POST https://auth.example.com/api/v1/auth/session/activity \
     -H "x-session-id: <session_id>" \
     -H "x-session-activity: <current activity token>"
   # → { "activity_token": "<new token>", "expires_at": "2026-08-11T18:42:00Z" }

   This call has its own rate limit; an over-limit refresh returns 429 with Retry-After, same as the other brakes in Errors & rate limits.

GET /api/v1/auth/me resolves a session to the user's identity and full memberships (org id, name, role key). Call it from your product backend with the API Access machine token (identity:read scope), passing the session in an x-session-id header and the current activity token in x-session-activity (see above). It is explicit about multi-org users:

• Exactly one membership → permissions and accessible apps are resolved automatically.
• Multiple memberships and no ?organization_id=… → identity + memberships only, with no permission block (never guessed).
• Pass ?organization_id=<uuid> to resolve permissions and apps for a specific organization.

Hosted authentication credentials use browser cookie names beginning with __Host-. Browsers accept that prefix only for secure, host-only cookies with Path=/ and noDomain attribute. The cookies are also HttpOnly and SameSite=Lax. A credential issued on one authentication hostname therefore cannot become an ambient credential for sibling hosts.

If your product uses the direct flow, the returned session is exchanged and stored by your backend. Your product's own browser session cookie is your responsibility: keep the bearer out of browser JavaScript, use a host-only secure cookie, rotate it when privilege changes, and clear it when the upstream session is revoked or expires. The hosted cookie does not authenticate your application and your application cookie does not authenticate the hosted origin.

If you host your own login pages, your backend can give users the same account-security controls as the hosted Authreads UI. Obtain a client-credentials token and call the routes below with an explicit user id. The credential supplies the tenant boundary; caller input can never select a tenant.

GET  /api/v1/auth/users/{user_id}/account-security/sessions
POST /api/v1/auth/users/{user_id}/account-security/sessions/{session_id}/revoke
POST /api/v1/auth/users/{user_id}/account-security/sessions/revoke-others
GET  /api/v1/auth/users/{user_id}/account-security/devices
POST /api/v1/auth/users/{user_id}/account-security/devices/{device_id}/revoke
POST /api/v1/auth/users/{user_id}/account-security/revoke-others-and-devices
GET  /api/v1/auth/users/{user_id}/account-security/policy

Reads and the renderable policy require account-security:read. Revocations requireaccount-security:manage. For “revoke others” and the combined action, send { "current_session_id": "<account_session_id>" }. Session inventory is tenant/user-pool scoped, not app-scoped — one sign-in reaches every app in the user's pool, so the list includes sessions started through other apps too. Each returned session still names the app it was originally created through, for display. Trusted devices are tenant/user-pool scoped for the same reason: the same trusted browser can authenticate the user across apps in that pool.

IP fields are display locations, not enforcement keys. Hosted/OIDC flows can return anobserved_client_ip because the browser reaches Authreads directly. Confidential BFF flows may return null with not_recorded when Authreads only saw your server. If your backend sends Authreads-End-User-IP, that claim is kept in audit provenance but is not echoed back as a session location.

// Session item
{ "ip": "203.0.113.7", "ip_source": "observed_client_ip" }
{ "ip": null, "ip_source": "not_recorded" }

// Trusted-device item
{
  "first_seen_ip": "203.0.113.7",
  "first_seen_ip_source": "observed_client_ip",
  "last_used_ip": null,
  "last_used_ip_source": "not_recorded"
}

The session list reflects both session clocks. A session is returned only if it is inside its absolute lifetime and has not passed the idle timeout, so a browser abandoned hours ago stops being listed without the user having to sign out. The trusted-device active_session_count uses the same rule, so the count always matches the number of sessions actually listed.

Each session carries last_activity_at, so you can render “last active 4 minutes ago” beside it.