Introduction
auth-ai is a Python SDK for applications that sign their users in through a CIRCLE auth-service instance. It covers the application side of the relationship: the OIDC sign-in, the session, the user's entitlements, the credit wallet, the LiteLLM gateway, and the machine-to-machine billing and consumption APIs.
It is installed from PyPI as auth-ai and imported as auth_ai. The Python and TypeScript SDKs share the same wire contract: the backend-for-frontend routes, the sealed sign-in cookie, the cookie names and the error codes.
0.x release: the public API is not stable yet. It is async only and needs Python 3.12 or later. See Release channels and the Roadmap.When to use it
Use auth-ai when your Python backend:
- signs users in with an auth-service instance and wants a server-side session instead of tokens in the browser;
- reads roles, permissions, plan features or the organisation from the user's claims;
- lets users call LLMs or MCP tools through the LiteLLM gateway and bills their credit wallet;
- reports consumption or reads a user's subscription and invoices from its backend;
- exposes its own API protected by auth-service bearer tokens.
It is built for auth-service, whose claims and wallet, billing and consumption REST routes it relies on. It is not a client for arbitrary OIDC providers and it is not an identity provider: to run the provider, see the auth-service documentation.
How it fits
Browser ──── session cookie (opaque, HttpOnly) ───▶ Your backend
│ auth_ai
OIDC code + PKCE, refresh, │
client_credentials, wallet ▼
auth-service
│ access token (audience = gateway)
▼
LiteLLM gateway ── debits the user's wallet
The browser never holds a token. Your backend holds one refresh-token chain per user and mints short-lived access tokens for each audience it needs. Read Architecture for the details.
What is in the box
| Module | Use it for |
|---|---|
auth_ai | The core: AuthClient, AuthClientConfig, GrantManager, AiClient, claims helpers, format_euros, the error registry. |
auth_ai.web | Framework-agnostic backend-for-frontend sign-in handlers (AuthHandlers), WebRequest and WebResponse, and the session store. |
auth_ai.starlette | The FastAPI and Starlette adapter: install_auth, require_auth, load_session. Needs the starlette or fastapi extra. |
auth_ai.server | Bearer token verification, back-channel logout, protected-resource metadata, and the billing and consumption API (MachineApi). |
Everything is async: the SDK uses httpx2 for HTTP and pydantic for validation, and ships type information.
What is not in the box
The browser client, the React bindings and the Vue bindings live in the TypeScript package @circle-rd/auth-ai. They talk to the routes that AuthHandlers serves, so they work unchanged against a Python backend: see Use the TypeScript client.
Next steps
- Install the package.
- Register your application in auth-service.
- Follow the Quick start to get a sign-in running.