Configuration
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.
| Option | Type | Default | Description |
|---|---|---|---|
issuer | str | required | auth-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_id | str | required | The application's OAuth client id (its slug). Non-empty. |
client_secret | SecretStr | None | None | Absent 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_uri | str | required | The callback URL registered in auth-service. HTTPS, or HTTP for localhost, 127.0.0.1 and ::1 only. |
post_logout_redirect_uri | str | None | None | Sent as post_logout_redirect_uri by logout_url(). Same URL rules as redirect_uri. |
scopes | tuple[str, ...] | DEFAULT_SCOPES | Must include openid; each scope is non-empty. A list is accepted and stored as a tuple. |
resources | tuple[str, ...] | () | RFC 8707 audiences requested at sign-in, each an absolute URL. Every refresh can narrow to one. |
gateway_url | str | None | None | Public URL of the LiteLLM gateway. HTTPS (or loopback HTTP), no trailing slash. Turns on the gateway and wallet audiences. |
clock_tolerance_seconds | int | 5 | Allowed clock skew when verifying tokens. From 0 to 300. |
timeout_seconds | float | 10.0 | Timeout 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.
| Option | Type | Default | Description |
|---|---|---|---|
auth | AuthClient | required | The OIDC client. |
grants | GrantManager | required | Stores the refresh token obtained at sign-in. |
sessions | SessionStore | required | Where sessions live. Use a database in production. |
secret | str | required | At least 32 characters, random. Seals the sign-in cookie. Keep it out of source control. |
base_path | str | "/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_redirect | str | "/" | Where users land after sign-in or sign-out without a target. |
session_ttl_seconds | int | 28800 (8 h) | Absolute lifetime of a session. Capped at the ID token's exp when no refresh token was issued. |
claims_renew_seconds | int | 900 | How often claims are renewed from the provider. |
require_provider_session | bool | True | Refuse an ID token without sid. |
error_redirect | str | None | None | Redirect target of a failed sign-in, with ?error=<code>. JSON 403 when unset. |
ai | AiClient | None | None | Adds the /wallet, /wallet/stats and /models routes. |
replay_store | ReplayStore | None | MemoryReplayStore() | Remembers accepted logout tokens. Share it across replicas. |
on_sessions_ended | Callable[[Sequence[Session]], Awaitable[None] | None] | None | None | Called after sessions end (sign-out or back-channel logout). May be a coroutine function. |
on_error | Callable[[BaseException], None] | None | None | Receives unexpected failures and the ones the response must not detail. |
Other constructors
| Constructor | Options | Notes |
|---|---|---|
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.