Getting started
Installation
Requirements, install commands with pip, uv and Poetry, the optional framework extras and the import paths of the package.
Requirements
- Python 3.12 or later (
requires-pythonis>=3.12). The test suite runs on Python 3.12, 3.13 and 3.14. - An asyncio application: the SDK is async only and has no synchronous facade.
- A CIRCLE auth-service instance and an application registered in it. See Register the application.
Install
pip install auth-ai
uv add auth-ai
poetry add auth-ai
See Release channels for how versions reach PyPI, including how to install a pre-release.
The SDK depends on httpx2[brotli,http2] (>=2.16), which negotiates HTTP/2 and gzip or brotli responses by default,, joserfc (>=1.7) and pydantic (>=2.12), which your installer resolves for you.
Optional extras
The framework adapter needs a framework. Install the extra that matches yours:
| Extra | Installs | Use it for |
|---|---|---|
auth-ai[fastapi] | fastapi>=0.115 | FastAPI applications. |
auth-ai[starlette] | starlette>=0.46 | Starlette applications. |
pip install "auth-ai[fastapi]"
uv add "auth-ai[fastapi]"
poetry add "auth-ai[fastapi]"
Without an extra, auth_ai, auth_ai.web and auth_ai.server work as they are; only auth_ai.starlette imports Starlette. The SDK does not install an ASGI server: bring your own, for example uvicorn.
Import paths
# Core: OIDC client, grants, AI clients, claims helpers, errors
from auth_ai import AuthClient, AuthClientConfig, GrantManager, AiClient
# Backend-for-frontend handlers, request and response types, session store
from auth_ai.web import AuthHandlers, MemorySessionStore, Session, WebRequest, WebResponse
# FastAPI and Starlette adapter (needs the fastapi or starlette extra)
from auth_ai.starlette import install_auth, require_auth, load_session
# Bearer verification, back-channel logout, protected-resource metadata, machine API
from auth_ai.server import BearerVerifier, MachineApi, require_scopes
The installed version is available as auth_ai.__version__. The full exports of each module are in the Reference.
Next step
Register your application in auth-service, then follow the Quick start.