CIRCLE
Reference

Configuration

Every option of AuthClient, AuthHandlers and the other constructors, with defaults and validation rules.

The SDK reads no environment variable: every value is passed in code. Validation happens when the object is created, and an invalid configuration raises CFG_001 (see Error codes) with the offending field names in the message. All constructors take keyword arguments (the options below are keyword-only), except where noted.

AuthClient(config, *, http_client=None)

AuthClient is the OIDC relying party. config is an AuthClientConfig or any mapping that AuthClientConfig accepts: a mapping is validated for you. AuthClientConfig is a frozen pydantic model that rejects unknown keys; the resolved configuration is available as auth.config.

OptionTypeDefaultDescription
issuerstrrequiredauth-service URL. HTTPS only (no loopback exception) and no trailing slash: it is compared verbatim to the iss claim, and discovery starts from it.
client_idstrrequiredThe application's OAuth client id (its slug). Non-empty.
client_secretSecretStr | NoneNoneAbsent for a public client, which then relies on PKCE alone. Needed by client_credentials and the machine API. A plain str is converted; read it back with get_secret_value().
token_endpoint_auth_method"client_secret_basic" | "client_secret_post""client_secret_basic"How the secret is sent to the token endpoint. Ignored without a client_secret.
redirect_uristrrequiredThe callback URL registered in auth-service. HTTPS, or HTTP for localhost, 127.0.0.1 and ::1 only.
post_logout_redirect_uristr | NoneNoneSent as post_logout_redirect_uri by logout_url(). Same URL rules as redirect_uri.
scopestuple[str, ...]DEFAULT_SCOPESMust include openid; each scope is non-empty. A list is accepted and stored as a tuple.
resourcestuple[str, ...]()RFC 8707 audiences requested at sign-in, each an absolute URL. Every refresh can narrow to one.
gateway_urlstr | NoneNonePublic URL of the LiteLLM gateway. HTTPS (or loopback HTTP), no trailing slash. Turns on the gateway and wallet audiences.
clock_tolerance_secondsint5Allowed clock skew when verifying tokens. From 0 to 300.
timeout_secondsfloat10.0Timeout of discovery, JWKS and API requests. Greater than zero.

DEFAULT_SCOPES is ("openid", "profile", "email", "roles", "permissions", "features", "offline_access").

With gateway_url, the resolved config adds wallet:self:read (exported as WALLET_SELF_SCOPE) to scopes, and the gateway URL and the issuer to resources, without duplicates.

from auth_ai import AuthClient

auth = AuthClient(
    {
        "issuer": "https://auth.example.com",
        "client_id": "my-app",
        "client_secret": "<client-secret>",
        "redirect_uri": "https://app.example.com/auth/callback",
        "post_logout_redirect_uri": "https://app.example.com/",
        "gateway_url": "https://llm.example.com",
        "resources": ["https://app.example.com"],
    }
)

print(auth.config.scopes[-1])  # wallet:self:read
print(auth.config.resources)  # the app, the gateway, then the issuer

http_client

http_client is an optional httpx2.AsyncClient that replaces the default one, for example to add a proxy, a transport or an observability layer. The client is used for every request, including the REST API clients built on this one (auth.http). The default client is built by build_http_client(): the configured timeout, HTTP/2 over TLS, gzip and brotli responses, and no redirects.

A client you pass is never closed by the SDK. When the SDK created the client, close it with await auth.aclose() or use async with AuthClient(...) as auth:.

AuthHandlers(...)

Built synchronously (no await). Details of the routes are in Web handlers and ASGI.

OptionTypeDefaultDescription
authAuthClientrequiredThe OIDC client.
grantsGrantManagerrequiredStores the refresh token obtained at sign-in.
sessionsSessionStorerequiredWhere sessions live. Use a database in production.
secretstrrequiredAt least 32 characters, random. Seals the sign-in cookie. Keep it out of source control.
base_pathstr"/auth"Prefix of the routes. Must start with /, not end with /, and use only letters, digits, /, _ and -. The path of redirect_uri must be <base_path>/callback.
default_redirectstr"/"Where users land after sign-in or sign-out without a target.
session_ttl_secondsint28800 (8 h)Absolute lifetime of a session. Capped at the ID token's exp when no refresh token was issued.
claims_renew_secondsint900How often claims are renewed from the provider.
require_provider_sessionboolTrueRefuse an ID token without sid.
error_redirectstr | NoneNoneRedirect target of a failed sign-in, with ?error=<code>. JSON 403 when unset.
aiAiClient | NoneNoneAdds the /wallet, /wallet/stats and /models routes.
replay_storeReplayStore | NoneMemoryReplayStore()Remembers accepted logout tokens. Share it across replicas.
on_sessions_endedCallable[[Sequence[Session]], Awaitable[None] | None] | NoneNoneCalled after sessions end (sign-out or back-channel logout). May be a coroutine function.
on_errorCallable[[BaseException], None] | NoneNoneReceives unexpected failures and the ones the response must not detail.

Other constructors

ConstructorOptionsNotes
GrantManager(*, auth, store, lock=None, expiry_skew_seconds=30)auth needs refresh and revoke; lock defaults to InProcessGrantLock().See Sessions and grants.
AiClient(*, auth, grants)auth needs config and http; grants needs get_access_token and invalidate.for_user(grant_id) returns a UserAi with wallet and gateway.
MachineApi(auth)auth needs client_credentials, config and http.Raises CFG_001 without a client_secret. Positional argument.
BearerVerifier(auth, *, audience)audience must be a URL.Raises CFG_001 otherwise. auth is positional.
BackchannelLogoutHandler(*, auth, on_logout, replay_store=None, on_error=None)replay_store defaults to MemoryReplayStore().For use without the sign-in handlers.
WebRequest.create(method, url, *, headers=None, body=b"")url is absolute.See Web handlers and ASGI.

GatewayClient(*, gateway_url, tokens, http, timeout_seconds) is exported, but you normally get one from ai.for_user(id).gateway, which wires the tokens for you. WalletClient is exported too, but its constructor takes an internal HTTP helper (auth_ai.http.JsonHttp): get it from ai.for_user(id).wallet.

Copyright © 2026