CIRCLE
Backend

FastAPI backend

A complete backend-for-frontend on FastAPI: sign-in, sessions, safe logging, same-origin protection, gateway and billing routes.

This guide extends the Quick start into the shape of a real service. It assumes the application is registered with LiteLLM support on, a back-channel logout URI, and the machine scopes. The same code works on plain Starlette: install_auth, require_auth and load_session take a Starlette application and request the same way.

Configuration values

VariableExamplePurpose
PUBLIC_URLhttps://app.example.comPublic origin of your application. No trailing slash.
AUTH_ISSUERhttps://auth.example.comauth-service URL.
AUTH_CLIENT_IDmy-appThe application's client id.
AUTH_CLIENT_SECRET<client-secret>Never commit it.
AUTH_COOKIE_SECRET<32+ random characters>Seals the sign-in cookie.
GATEWAY_URLhttps://llm.example.comThe LiteLLM gateway, when used.

These names are yours: the SDK reads no environment variable.

The server

main.py
import logging
import os
from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
from contextlib import asynccontextmanager
from typing import Annotated

from fastapi import Depends, FastAPI, Request, Response
from fastapi.responses import JSONResponse

from auth_ai import (
    ERR,
    AiClient,
    AuthAiError,
    AuthClient,
    GatewayModel,
    GrantManager,
    MemoryGrantStore,
)
from auth_ai.starlette import install_auth, require_auth
from auth_ai.web import AuthHandlers, MemorySessionStore, Session

logger = logging.getLogger("app")


def env(name: str) -> str:
    value = os.environ.get(name)
    if not value:
        raise RuntimeError(f"Missing environment variable {name}")
    return value


public_url = env("PUBLIC_URL")

auth = AuthClient(
    {
        "issuer": env("AUTH_ISSUER"),
        "client_id": env("AUTH_CLIENT_ID"),
        "client_secret": env("AUTH_CLIENT_SECRET"),
        "redirect_uri": f"{public_url}/auth/callback",
        "post_logout_redirect_uri": f"{public_url}/auth/logout/callback",
        "gateway_url": env("GATEWAY_URL"),
    }
)

# In memory: fine for a demo or one instance. Use database stores in production.
grants = GrantManager(auth=auth, store=MemoryGrantStore())
ai = AiClient(auth=auth, grants=grants)


def log_auth_error(error: BaseException) -> None:
    # Details belong in logs, never in responses.
    detail = error.to_json() if isinstance(error, AuthAiError) else str(error)
    logger.warning("auth handler error", extra={"error": detail})


def log_sessions_ended(sessions: Sequence[Session]) -> None:
    logger.info("sessions ended", extra={"count": len(sessions)})


handlers = AuthHandlers(
    auth=auth,
    grants=grants,
    sessions=MemorySessionStore(),
    secret=env("AUTH_COOKIE_SECRET"),
    ai=ai,  # adds /auth/wallet, /auth/wallet/stats and /auth/models for the frontend
    on_error=log_auth_error,
    on_sessions_ended=log_sessions_ended,
)


@asynccontextmanager
async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
    yield
    await auth.aclose()


app = FastAPI(lifespan=lifespan)
install_auth(app, handlers)


# State-changing API calls must come from this site.
@app.middleware("http")
async def same_origin_api(
    request: Request, call_next: Callable[[Request], Awaitable[Response]]
) -> Response:
    mutating = request.method not in {"GET", "HEAD", "OPTIONS"}
    if mutating and request.url.path.startswith("/api/"):
        request_origin = request.headers.get("origin")
        if request_origin is not None and request_origin != handlers.origin:
            return JSONResponse({"error": ERR.SES_004().to_public_json()}, status_code=403)
    return await call_next(request)


current_session = require_auth(handlers)
SessionDep = Annotated[Session, Depends(current_session)]


@app.get("/api/models")
async def list_models(session: SessionDep) -> list[GatewayModel]:
    return await ai.for_user(session.user_id).gateway.list_models()

What each piece does

  • install_auth adds one catch-all route below handlers.base_path (/auth by default) and an exception handler that answers any AuthAiError with the public error envelope.
  • on_error receives the cause of every failed callback, every unexpected failure, and a failed grant revocation. The browser only ever sees the generic code. See Security model.
  • on_sessions_ended fires after a sign-out or a back-channel logout: close WebSockets, drop per-user caches. It may be a plain function or a coroutine function.
  • The middleware applies the Origin check the SDK enforces only on /auth/logout to your own state-changing routes. It compares with handlers.origin, the origin of your registered redirect_uri.
  • Proxies. The SDK never reads the Host or X-Forwarded-* headers to build URLs: it builds them on the origin of redirect_uri. Your ASGI server's proxy settings only matter for your own logging and client IPs.

Protecting routes

DependencyEffect
require_auth(handlers)Answers 401 SES_001 when signed out; returns the Session otherwise.
load_session(handlers)Returns the Session when signed in and None otherwise.

Both factories return an async function that takes the Starlette Request: use it with Depends(...) in FastAPI, or call it with the request in a Starlette endpoint. Build the dependency once, at module level, as current_session does above.

Check entitlements on the server, in the route that does the work:

from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.responses import JSONResponse

from auth_ai import has_permission
from auth_ai.starlette import require_auth
from auth_ai.web import AuthHandlers, Session


def add_report_routes(app: FastAPI, handlers: AuthHandlers) -> None:
    current_session = require_auth(handlers)

    @app.post("/api/reports", response_model=None)
    async def create_report(
        session: Annotated[Session, Depends(current_session)],
    ) -> dict[str, bool] | JSONResponse:
        if not has_permission(session.claims, "reports", "write"):
            return JSONResponse({"error": {"code": "FORBIDDEN"}}, status_code=403)
        return {"created": True}

FORBIDDEN is an example of your own application's error code: the SDK registry has no authorisation code of that kind.

When a route of yours raises an AuthAiError (for example GW_001 from the gateway), the handler installed by install_auth answers with the status of the error table and the public envelope.

Serving the frontend

install_auth only answers below base_path. Serve your static frontend however you like (for example Starlette's StaticFiles); the browser calls /auth/me to learn who is signed in. See Use the TypeScript client.

Keep the authorization code out of the logs

The callback URL carries the authorization code in its query string, and uvicorn's access log prints the full request line. Strip the query string with a logging filter:

import logging


class QueryStripFilter(logging.Filter):
    """Keeps query strings, which carry the authorization code, out of the access log."""

    def filter(self, record: logging.LogRecord) -> bool:
        if isinstance(record.args, tuple) and len(record.args) == 5:
            client, method, path, http_version, status = record.args
            record.args = (client, method, str(path).split("?", 1)[0], http_version, status)
        return True


logging.getLogger("uvicorn.access").addFilter(QueryStripFilter())

The filter relies on uvicorn's access log record layout (client, method, path, HTTP version, status). Adapt it to your server, or disable its access log.

Next

Copyright © 2026