CIRCLE
Operations

Production checklist

What to change before the first real user signs in: stores, locks, secrets, URLs, logout, logging and dependencies.

The quick start and the example app use in-memory stores so that they run with no setup. Work through this list before deploying.

Storage

  • SessionStore on your database. MemorySessionStore loses every session on restart and cannot be shared. Index user_id and the provider session id, and purge expired rows. See Implement the stores.
  • GrantStore on your database, encrypted at rest. It holds one long-lived refresh token per user.
  • A distributed GrantLock when you run several replicas (or several worker processes), so two of them never rotate the same grant at once. The default lock only covers one process.
  • A shared ReplayStore when you run several replicas (for example Redis SET NX PX), so a logout token replayed on another instance is refused.

Secrets

  • Cookie secret of at least 32 random characters (openssl rand -base64 48), from your secret manager or environment. Shorter secrets are refused with CFG_001. Rotating it only invalidates sign-ins in progress: the session cookie is an opaque random id and is not sealed with it.
  • Client secret from the environment. Without client_secret the SDK acts as a public client and the machine API is unavailable, so fail at startup on a missing variable rather than passing None.
  • Nothing secret in source control, logs or error responses.

URLs and registration

  • redirect_uri is <origin><base_path>/callback, over HTTPS, and registered identically in auth-service. AuthHandlers refuses a mismatch.
  • post_logout_redirect_uri is registered if you set it.
  • Back-channel logout URI <origin><base_path>/backchannel-logout is registered in auth-service: HTTPS and reachable from auth-service. auth-service waits for these deliveries when a user signs out, so keep the endpoint fast.
  • End-session or the back-channel URI is enabled, so the ID token carries sid. Keep require_provider_session at its default (True).
  • LiteLLM support is on and gateway_url matches the gateway URL exactly (no trailing slash), when you use the gateway.
  • Machine scopes billing:read, consumption:read, consumption:write are granted, when you use the machine API.
  • Your reverse proxy forwards the /auth/* paths, the Cookie, Origin and Sec-Fetch-Site headers and the request body of the back-channel route unchanged, and terminates TLS (consider HSTS).

Application behaviour

  • Entitlements are enforced on the server, in each route, not only hidden in the UI.
  • Your own POST, PUT, PATCH and DELETE routes check Origin, as the SDK does for /auth/logout.
  • The back-channel route stays outside session and CSRF protection: it is called without cookies.
  • on_sessions_ended closes sockets or drops caches of the users whose sessions ended.
  • Tune session_ttl_seconds (8 hours by default) and claims_renew_seconds (15 minutes by default) to how quickly role and plan changes must reach users.
  • await auth.aclose() runs when the application stops (a FastAPI lifespan, for example), unless you passed your own http_client, which the SDK never closes.

Logging and errors

  • on_error is set and logs error.to_json() for AuthAiErrors: it is the only place the real cause of a failed sign-in appears.
  • Query strings are not logged: the callback URL carries the authorization code. uvicorn's access log prints them by default: see Keep the authorization code out of the logs.
  • Responses use to_public_json(), never message or details.

Dependencies and runtime

  • Python 3.12 or later.
  • Server clocks are synchronised (token verification allows clock_tolerance_seconds, 5 by default).
  • Dependency audit in CI (pip-audit).

Verify end to end

Run the example app against your auth-service and click Self-test: it exercises sign-in, claims renewal, per-audience tokens, introspection, the wallet, the gateway, billing and consumption, and writes a report free of any token or secret to the server log.

Copyright © 2026