FastAPI backend
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
| Variable | Example | Purpose |
|---|---|---|
PUBLIC_URL | https://app.example.com | Public origin of your application. No trailing slash. |
AUTH_ISSUER | https://auth.example.com | auth-service URL. |
AUTH_CLIENT_ID | my-app | The application's client id. |
AUTH_CLIENT_SECRET | <client-secret> | Never commit it. |
AUTH_COOKIE_SECRET | <32+ random characters> | Seals the sign-in cookie. |
GATEWAY_URL | https://llm.example.com | The LiteLLM gateway, when used. |
These names are yours: the SDK reads no environment variable.
The server
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_authadds one catch-all route belowhandlers.base_path(/authby default) and an exception handler that answers anyAuthAiErrorwith the public error envelope.on_errorreceives 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_endedfires 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
Origincheck the SDK enforces only on/auth/logoutto your own state-changing routes. It compares withhandlers.origin, the origin of your registeredredirect_uri. - Proxies. The SDK never reads the
HostorX-Forwarded-*headers to build URLs: it builds them on the origin ofredirect_uri. Your ASGI server's proxy settings only matter for your own logging and client IPs.
Protecting routes
| Dependency | Effect |
|---|---|
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
- Call the LiteLLM gateway and read billing.
- Implement the stores on your database.
- The Production checklist.
Security model
The protections built into the SDK, the error policy that keeps details out of responses, and what remains your responsibility.
Other frameworks
Mount the framework-agnostic sign-in handlers in a plain ASGI application, Litestar or Django, with a small bridge between WebRequest, WebResponse and your framework.