Skip to main content

CIRCLE auth-ai logo

CIRCLE auth-ai for Python

The Python SDK for CIRCLE auth-service — sign-in, entitlements, billing and LLM credit, in one library.

CI PyPI Python License: MIT Typed auth-service

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.typed and is checked with mypy --strict.
  • Async all the way. Built on httpx2 and asyncio; bring your own httpx2.AsyncClient for 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, state and nonce, 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-Authenticate challenges (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 httpx2 client that signs OpenAI-compatible calls with a fresh user token (hand it to the openai package); model, agent and MCP server listing; gateway errors mapped (402 → GW_001, 429 with Retry-After, …).
  • Wallet reads: balance, spend statistics, per-session usage, transactions, top-up link. Amounts are exact int micro-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 → WebResponse handlers (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 SessionStore and GrantStore on 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 shared ReplayStore for 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_uri is <origin><base_path>/callback and the back-channel URI is <origin><base_path>/backchannel-logout, reachable over HTTPS by auth-service.
  • Log with on_error, answer with to_public_json(). Never forward error.message or error.details to a browser.
  • Keep your ASGI stack current: keep starlette / fastapi on 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.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for auth-ai 0.3.0
File Size Uploaded Provenance Actions
auth_ai-0.3.0.tar.gz 50.4 kB With provenance Details for auth_ai-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for auth-ai 0.3.0
File Interpreter ABI Platform Actions
auth_ai-0.3.0-py3-none-any.whl Python 3 none any Details for auth_ai-0.3.0-py3-none-any.whl

Total release size: 114.4 kB

Release files / auth_ai-0.3.0.tar.gz

Download URL auth_ai-0.3.0.tar.gz
Size 50.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7a9a5ff3d6fa21f4a93c7c706ead5fb9373aa5e918f6f979047e32190d1662eb
BLAKE2b-256 checksum
How to use checksums
25b9cfaa6245cdd0e83ace7b4ca8386e4f67dd9c764b6ee5cf2fa1a4b153c249
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 7, 2026.

Transparency log

Release files / auth_ai-0.3.0-py3-none-any.whl

Download URL auth_ai-0.3.0-py3-none-any.whl
Size 64.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d0f65aad7363461d90b6cb20ce4d2051b5992c1d1171e137e2ba158cebe0512d
BLAKE2b-256 checksum
How to use checksums
d77b9e241936b98d4912578778b2042237c9d8920504efb7cd3d2cd655aa0092
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 7, 2026.

Transparency log

Security for auth-ai 0.3.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.

Select from 2 files

Attestation for auth_ai-0.3.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 7, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page