CIRCLE
Operations

Example app

Run examples/minimal, a FastAPI backend with a vanilla page that exercises the SDK against a real auth-service, with a built-in self-test.

examples/minimal in the repository is a deployable FastAPI application that exercises the SDK end to end against a real auth-service. It is the Python counterpart of the TypeScript SDK's example app and runs the same Self-test. Use it to validate a new auth-service setup, and as a reference for wiring.

The example's own README is the source of truth for its files, its configuration variables and its run options: read it in the repository rather than relying on a copy here.

What it needs

  • A registered application in auth-service: a confidential application with LiteLLM support on, a redirect URI, a post-logout URI and a back-channel logout URI on the host where you deploy the example, and the machine scopes billing:read, consumption:read and consumption:write. See Register the application.
  • A LiteLLM gateway URL and the application's client secret, which you provide as configuration of the example (never commit them).
  • For the compose deployment, the shared Traefik setup described in the example's README.

Run it

From a clone of the repository, with the configuration filled in as the example's README describes:

docker compose -f examples/minimal/compose.yml up -d --build

The image builds from the repository root, so the example runs the SDK source next to it.

The example keeps sessions and grants in memory: a restart signs everyone out. Use database-backed stores in a real application, see Production checklist.

The self-test

Sign in, then click Self-test. It runs its checks for your user and writes a report, free of any token or secret, to the server log. The checks are the ones listed on the TypeScript example page: session claims, claims renewal, per-audience tokens, bearer verification, introspection, the wallet, the gateway, billing and consumption.

Checks that call a model fail with a "no model matching" message when the user's plan does not include the models they look for: that is a property of your gateway setup, not an SDK problem.

Run the example against your auth-service before the first deployment of your own application and after any change that touches sign-in, tokens, the wallet or the gateway.

Copyright © 2026