CIRCLE
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-python is >=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

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:

ExtraInstallsUse it for
auth-ai[fastapi]fastapi>=0.115FastAPI applications.
auth-ai[starlette]starlette>=0.46Starlette applications.
pip install "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.

Copyright © 2026