CIRCLE auth-ai for Python
The Python SDK for CIRCLE auth-service — sign-in, entitlements, billing and LLM credit, in one library.
Let your application sign users in with a self-hosted CIRCLE auth-service, read what they are entitled to (roles, permissions, plan features), meter what they consume, and call LLMs on their behalf through a LiteLLM gateway that bills their credit wallet — without writing any OAuth, token refresh, logout or billing plumbing yourself.
This is the Python port of @circle-rd/auth-ai:
same behaviours, same wire contract, same error codes. A Python backend can serve
the TypeScript browser client and the React and Vue bindings unchanged.
Full documentation: https://docs.circle-cyber.com/auth-ai/python/
handlers = AuthHandlers(auth=auth, grants=grants, sessions=sessions, secret=secret, ai=ai)
install_auth(app, handlers) # /auth/login, /callback, /me, /logout…
@app.get("/api/models")
async def models(session: Session = Depends(require_auth(handlers))):
return await ai.for_user(session.user_id).gateway.list_models()
Principles
- Do not reinvent OAuth or JOSE. Signature, JWT and cookie encryption work stays with the maintained library joserfc and HTTP with httpx2; the SDK adds what is specific to auth-service on top of them. The declared direct runtime dependencies are licensed under BSD-3-Clause or MIT.
- Backend-for-frontend by default. The browser holds one opaque session cookie. Access and refresh tokens never reach it.
- Fail loud, leak nothing. Invalid state is rejected, not repaired. Errors carry stable codes; HTTP responses expose the code and a generic message, and the detail stays in your logs.
- Strict at every boundary. Every external payload (tokens, API answers,
cookies, configuration) is validated with pydantic;
the package ships
py.typedand is checked withmypy --strict. - Async all the way. Built on httpx2 and
asyncio; bring your ownhttpx2.AsyncClientfor proxies, transports or tracing. - Centralized spending. The SDK never debits a wallet itself: the gateway bills each call, so margin and pricing stay under the administrator's control.
Features
Sign-in and sessions
- Authorization-code flow with PKCE,
stateandnonce, multi-audience tokens (RFC 8707), TOTP handled by the provider. - One serialized refresh-token chain per user, with per-audience access tokens minted on demand and never stored.
- Sealed one-shot login cookie, hashed session ids,
__Host-cookies, same-origin redirect targets, refused cross-site logout. - Claims (roles, permissions, features, plan, organization) renewed from the provider on a schedule.
- Back-channel logout: signature,
typ, audience, event, lifetime and replay checks, then the sessions and grant of the user end.
Entitlements
- Typed claims and helpers:
has_role,has_permission(write implies read),has_feature,get_feature. - Bearer-token verification for your own API, with RFC 9728
protected-resource metadata and
WWW-Authenticatechallenges (MCP-friendly).
LLM gateway and credit wallet
- One switch in auth-service ("LiteLLM support") and one option here
(
gateway_url) turn on the gateway and wallet audiences. - An origin-locked
httpx2client that signs OpenAI-compatible calls with a fresh user token (hand it to theopenaipackage); model, agent and MCP server listing; gateway errors mapped (402→GW_001,429withRetry-After, …). - Wallet reads: balance, spend statistics, per-session usage, transactions,
top-up link. Amounts are exact
intmicro-euros.
Billing and consumption
- Machine client (
client_credentials, cached and single-flighted): a user's subscription, metered usage and invoices; usage reporting with idempotency keys for features billed per call.
Delivery
- Framework-agnostic
WebRequest→WebResponsehandlers (mount them anywhere) and a Starlette / FastAPI adapter. - Python 3.12+ (tested on 3.12, 3.13 and 3.14), full type declarations, MIT licensed.
Install
pip install "auth-ai[fastapi]" # or auth-ai[starlette], or plain auth-ai
Register your application in auth-service first: a confidential application with
the LiteLLM support switch on (if you call the gateway), the redirect URI
https://<host>/auth/callback and the back-channel logout URI
https://<host>/auth/backchannel-logout.
Quick start
A FastAPI backend (the stores below live in memory: demo only, see Production):
import os
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from fastapi import Depends, FastAPI
from auth_ai import AiClient, AuthClient, GrantManager, MemoryGrantStore
from auth_ai.starlette import install_auth, require_auth
from auth_ai.web import AuthHandlers, MemorySessionStore, Session
auth = AuthClient(
{
"issuer": "https://auth.example.com",
"client_id": "my-app",
"client_secret": os.environ["AUTH_CLIENT_SECRET"],
"redirect_uri": "https://app.example.com/auth/callback",
"gateway_url": "https://llm.example.com",
}
)
grants = GrantManager(auth=auth, store=MemoryGrantStore())
ai = AiClient(auth=auth, grants=grants)
handlers = AuthHandlers(
auth=auth,
grants=grants,
ai=ai, # adds /auth/wallet, /auth/wallet/stats and /auth/models for your frontend
sessions=MemorySessionStore(),
secret=os.environ["COOKIE_SECRET"], # 32+ random characters
)
@asynccontextmanager
async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
yield
await auth.aclose()
app = FastAPI(lifespan=lifespan)
install_auth(app, handlers)
@app.get("/api/models")
async def models(session: Session = Depends(require_auth(handlers))):
return await ai.for_user(session.user_id).gateway.list_models()
Calling the gateway with the openai package (or any OpenAI-compatible SDK that
takes an httpx2 client):
from openai import AsyncOpenAI
gateway = ai.for_user(user_id).gateway
async with gateway.create_http_client() as http_client:
client = AsyncOpenAI(
base_url=gateway.openai_base_url,
api_key="unused", # replaced by a fresh user token on every request
http_client=http_client,
)
answer = await client.chat.completions.create(
model="my-model", messages=[{"role": "user", "content": "Hello"}]
)
Reporting usage for a feature billed per call, from your backend:
from auth_ai.server import MachineApi
machine = MachineApi(auth)
await machine.consumption.report(user_id, "audits", 1, idempotency_key="audit-42")
A complete, deployable application lives in examples/minimal.
Modules
| Import | What it gives you |
|---|---|
auth_ai |
OIDC client, grants, claims helpers, wallet and gateway clients, error registry |
auth_ai.server |
Bearer verification, back-channel logout, protected-resource metadata, machine API |
auth_ai.web |
Sign-in handlers (WebRequest → WebResponse), session store contract |
auth_ai.starlette |
install_auth, require_auth and load_session for Starlette and FastAPI (starlette ≥ 0.46) |
Architecture
sequenceDiagram
autonumber
participant B as Browser
participant A as Your backend (auth-ai)
participant S as auth-service
participant G as LiteLLM gateway
B->>A: GET /auth/login
A-->>B: 302 to auth-service (PKCE, resources) + sealed cookie
B->>S: sign in (password, TOTP…)
S-->>B: 302 /auth/callback?code
B->>A: GET /auth/callback
A->>S: code → tokens (client secret)
A-->>B: 303 + opaque session cookie
B->>A: GET /auth/wallet (cookie)
A->>S: wallet read (user token for auth-service)
B->>A: POST /api/chat (cookie)
A->>G: call (user token for the gateway)
G->>S: debit the wallet after the call
S-->>A: back-channel logout on sign-out anywhere
auth-ai-py/
├── 📁 src/auth_ai/
│ ├── client.py AuthClient — discovery, PKCE login, refresh, logout, revoke, introspect
│ ├── config.py Validated configuration (gateway_url adds the gateway audiences)
│ ├── grants.py GrantManager — serialized refresh rotation, per-audience tokens
│ ├── claims.py Claim models and entitlement helpers
│ ├── wallet.py WalletClient and wallet models (int micro-euros)
│ ├── gateway.py GatewayClient — origin-locked httpx2 client, listings, MCP URLs
│ ├── ai.py AiClient.for_user(grant_id)
│ ├── errors.py AuthAiError + ERR registry (OIDC_*, TOK_*, GW_*, SES_*…)
│ ├── 📁 server/ Bearer verification, back-channel logout, machine API
│ ├── 📁 web/ Sign-in handlers, sealed cookies, session store contract
│ └── starlette.py Starlette / FastAPI adapter
├── 📁 tests/ pytest suite on a scripted identity provider (no network)
├── 📁 examples/minimal/ Deployable end-to-end app with a self-test
└── 📁 docs-site/ Docus documentation (built into a container image)
Production
The SDK is storage-agnostic on purpose. Before going live:
- Persist sessions and grants. Implement
SessionStoreandGrantStoreon your database. The in-memory stores sign everyone out on restart and cannot be shared by replicas. - Several replicas? Provide a distributed
GrantLock(a refresh token rotates on every use; a replayed one revokes the whole family) and a sharedReplayStorefor back-channel logout tokens. - Secrets from the environment only: the client secret and a 32+ character cookie secret. Neither is ever logged or returned.
- Registered URIs must match:
redirect_uriis<origin><base_path>/callbackand the back-channel URI is<origin><base_path>/backchannel-logout, reachable over HTTPS by auth-service. - Log with
on_error, answer withto_public_json(). Never forwarderror.messageorerror.detailsto a browser. - Keep your ASGI stack current: keep
starlette/fastapion a release that carries the latest security fixes.
Documentation
The full documentation is published at docs.circle-cyber.com/auth-ai/python: concepts, one guide per framework, the configuration and API reference, the error-code registry and a production checklist.
For AI agents — the documentation is exposed through a built-in MCP server (HTTP), so agents can query it directly:
| Environment | MCP endpoint |
|---|---|
| Production | https://docs.circle-cyber.com/auth-ai/python/mcp |
| Local dev | http://localhost:3000/mcp (run npm run dev in docs-site/) |
Contributing — the development rules in AGENTS.md (naming, typing strictness, error handling, testing, security) and the process in CONTRIBUTING.md are mandatory for any contribution. Security reports: see SECURITY.md. Releases are tracked in CHANGELOG.md.
Roadmap
- More adapters (Django, Flask, Litestar) on top of the framework-agnostic handlers, as needs appear.
- A synchronous facade, if a real need shows up.
Credits & license
Built and maintained by CIRCLE. Stands on the shoulders of joserfc, httpx2, pydantic and Starlette.
Licensed under the MIT License — see LICENSE.
Metadata
Release files for auth-ai 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| auth_ai-0.2.0.tar.gz | 48.1 kB | With provenance | Details for auth_ai-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| auth_ai-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for auth_ai-0.2.0-py3-none-any.whl |
Total release size: 110.1 kB
Release files / auth_ai-0.2.0.tar.gz
| Download URL | auth_ai-0.2.0.tar.gz |
|---|---|
| Size | 48.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f3776a30b6487bc0b23696df4b4bbe705dc95c74726ab5fc41f594d9a4d7582b
|
|
BLAKE2b-256 checksum How to use checksums |
a919ec4610068983a45852307d8d6d204683c10a4229adb1b23790849b5a5ea9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logRelease files / auth_ai-0.2.0-py3-none-any.whl
| Download URL | auth_ai-0.2.0-py3-none-any.whl |
|---|---|
| Size | 62.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
329105acfcd5cf678552e7750328249c9f3f261abb6ddd3f8933f3aefb0f8d90
|
|
BLAKE2b-256 checksum How to use checksums |
fab540fdb52993c741f290b9ac3a2dfe3b0401b5c691cc6745af739ed6934118
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logSecurity for auth-ai 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for auth_ai-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.