CIRCLE

CIRCLE auth-ai (Python)

A Python SDK for applications that sign their users in through a CIRCLE auth-service. Run the OIDC flow on your asyncio backend, keep tokens off the browser, read roles and plan features, and let users call LLMs through the LiteLLM gateway against their credit wallet. It is the Python port of the TypeScript SDK, with the same wire contract.

What it does

    Backend-for-frontend sign-in
    Authorization code flow with PKCE on your server. The browser only holds an opaque, HttpOnly session cookie: access and refresh tokens never reach it.
    Grants and per-audience tokens
    One refresh-token chain per user, rotated under a lock, and short-lived access tokens minted per audience (RFC 8707) for your API, the gateway and auth-service.
    Entitlements from claims
    Roles, permissions, plan features and organisation are read from the ID token and renewed from the provider on a schedule. has_role, has_permission, has_feature and get_feature are typed helpers.
    Back-channel logout
    OIDC Back-Channel Logout verified and replay-protected: signing out of auth-service ends your local sessions and revokes the grant.
    Credit wallet and LiteLLM gateway
    Read the user's prepaid balance and spend, and call an OpenAI-compatible gateway with the user's own token through an httpx2 client. The gateway debits the wallet; your app never handles a debit.
    Billing and consumption
    From your backend with a machine token: read a user's subscription, metered usage and invoices, and report consumption with idempotency keys.
    Protect an API
    Verify JWT bearer tokens for your own audience, require scopes, and publish RFC 9728 protected-resource metadata so MCP and OAuth clients can discover the provider.
    FastAPI, Starlette, any ASGI framework
    An adapter for FastAPI and Starlette, and framework-agnostic WebRequest and WebResponse handlers you can bridge to any other framework.
    Async and typed
    Python 3.12 or later, built on httpx2 and pydantic, shipped with type information (py.typed). Pair it with the TypeScript browser client and the React and Vue bindings.
    Errors safe to show
    Every failure is an AuthAiError with a stable code. Details stay in your logs; HTTP responses carry the code and a generic message only.
Copyright © 2026