CIRCLE
Concepts

Architecture

The backend-for-frontend model: what the browser holds, what the server holds, and how a sign-in, a request and a sign-out flow through the SDK.

Backend-for-frontend

auth-ai runs the OIDC flow on your backend. The browser only holds an opaque session cookie; access, refresh and ID tokens never reach it. This removes the whole class of token theft from browser storage and XSS, and it lets the server end a session at any time.

Held byWhat
BrowserOne opaque cookie (__Host-aai_session on HTTPS, aai_session on loopback HTTP). A short-lived sealed aai_login cookie exists only during sign-in.
Your session storeA Session record keyed by the SHA-256 of the cookie value, so a leaked store cannot be replayed as cookies. It holds the claims and the ID token.
Your grant storeOne refresh token per user: the grant.
Memory of the processCached access tokens, never persisted.

Sign-in

  1. GET /auth/login calls AuthClient.startLogin(), which generates state, nonce and a PKCE verifier. They are sealed (AES-256-GCM, 10 minutes) into the aai_login cookie together with the validated next path, and the browser is redirected to auth-service.
  2. After sign-in, auth-service redirects to /auth/callback. The SDK rebuilds the callback URL on the registered redirectUri (never on the Host header), exchanges the code, and verifies the ID token: signature, issuer, audience, expiry and nonce.
  3. The ID token must carry sid, the provider session id that a back-channel logout names. Otherwise the sign-in fails (see requireProviderSession).
  4. The refresh token is saved in the GrantManager under the user's sub. A session is created, and the browser is redirected (303) to next with the session cookie.

When the provider issues no refresh token (no offline_access), no grant is saved and the session ends with the ID token's exp.

Each request

getSession(request) reads the cookie, hashes it and loads the session. When claimsRenewSeconds (900 by default) have passed, the claims are renewed first: the grant manager refreshes the token set, the new ID token is verified, and the session is updated. This is how a role change or a plan upgrade in auth-service reaches your application without a new sign-in. Two simultaneous requests of one session share a single renewal.

If the provider rejects the grant (invalid_grant), the session is ended and the request is treated as signed out. If the provider is unreachable, the request fails with the error and the session is kept: a network failure does not sign anyone out. A refreshed ID token that belongs to another user ends the session and raises TOK_001.

Calling other services

Your backend turns the single grant into tokens for each audience: your own API, auth-service (wallet) and the LiteLLM gateway. See Sessions and grants.

Sign-out

  • From your application: POST /auth/logout deletes the session and clears the cookie. When the user has no other session left, the grant is revoked at the provider. The answer carries the provider's logout URL so the single sign-on session ends too.
  • From elsewhere: auth-service posts a logout token to /auth/backchannel-logout. The SDK verifies it, deletes every session bound to that sid, and revokes the grants of users left without a session.

Use the onSessionsEnded option to close sockets or drop caches when sessions end either way.

Copyright © 2026