CIRCLE
Getting started

Introduction

What CIRCLE auth-ai (Python) is, when to use it, and how it fits between your application and auth-service.

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.

The SDK is a 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.
Pairing this Python backend with a browser frontend? The TypeScript SDK provides the browser client and React and Vue bindings, which work with this package's backend-for-frontend handlers.

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

ModuleUse it for
auth_aiThe core: AuthClient, AuthClientConfig, GrantManager, AiClient, claims helpers, format_euros, the error registry.
auth_ai.webFramework-agnostic backend-for-frontend sign-in handlers (AuthHandlers), WebRequest and WebResponse, and the session store.
auth_ai.starletteThe FastAPI and Starlette adapter: install_auth, require_auth, load_session. Needs the starlette or fastapi extra.
auth_ai.serverBearer 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

  1. Install the package.
  2. Register your application in auth-service.
  3. Follow the Quick start to get a sign-in running.
Copyright © 2026