Example app
examples/minimal in the repository is a deployable application that exercises the SDK end to end: sign-in with PKCE, the session cookie, entitlements, the wallet, the LiteLLM gateway (models, agents, MCP servers, chat, embeddings), back-channel logout, machine tokens, billing and consumption. Use it to validate a new auth-service setup, and as a reference for wiring.
What is in it
| File | Role |
|---|---|
server/main.ts | The Fastify backend: createAuthClient, GrantManager, createAiClient, createMachineApi, createAuthHandlers, authPlugin, the protected routes, a Bearer-protected route and the protected-resource metadata. |
server/config.ts | Reads and validates the environment; names the offending variables, never their values. |
server/selftest.ts | The self-test: sixteen checks that run for the signed-in user. |
web/ | A vanilla TypeScript page using @circle-rd/auth-ai/client. |
Dockerfile, compose.yml | Build and deploy behind Traefik. |
The backend sets a strict CSP (default-src 'self'; frame-ancestors 'none'), X-Content-Type-Options: nosniff, an Origin check on mutating /api/ routes, and logs request paths without query strings.
Register the application in auth-service
- A confidential application at
https://<host>, with LiteLLM support on. - Redirect URI
https://<host>/auth/callbackand post-logout URIhttps://<host>/. - Back-channel logout URI
https://<host>/auth/backchannel-logout. - Machine scopes
billing:read,consumption:readandconsumption:write(set by a superadmin if the application predates the default).
Configuration
The server reads these variables and refuses to start if one is invalid:
| Variable | Default | Description |
|---|---|---|
PORT | 3000 | Listening port. |
PUBLIC_URL | required | Public URL of the app, for example https://test.example.com. |
AUTH_ISSUER | required | auth-service URL. |
AUTH_CLIENT_ID | required | The application's client id. |
AUTH_CLIENT_SECRET | required | The client secret. A secret: never commit it. |
GATEWAY_URL | required | The LiteLLM gateway URL. |
COOKIE_SECRET | required | At least 32 random characters. A secret. |
compose.yml sets everything but the two secrets: PUBLIC_URL is https://${APP_HOST}, with APP_HOST, AUTH_ISSUER, AUTH_CLIENT_ID and GATEWAY_URL overridable from the environment of the compose command. Put the secrets in an untracked .env file, created from .env.example. Compose resolves env_file: .env relative to the compose file, so it belongs in examples/minimal/:
AUTH_CLIENT_SECRET=<client-secret>
# 32+ random characters, e.g. `openssl rand -base64 48`
COOKIE_SECRET=<random-secret>
Run it
From a clone of the repository:
pnpm install && pnpm build && pnpm example:build
docker compose -f examples/minimal/compose.yml up -d --build
compose.yml expects the shared Traefik setup: an external Docker network named edge, a Traefik with a websecure entry point and a letsencrypt certificate resolver, and a host name pointing at it (APP_HOST). Adapt the labels if your edge is different. The image builds from the repository root, because the example imports the SDK it ships with.
The self-test
Sign in, then click Self-test. It runs these checks for your user and logs a report that holds no token or secret:
| Check | What it verifies |
|---|---|
session-claims | The session carries sid, roles, permissions, features, plan and organisation. |
refresh-returns-id-token | A refresh rotates the token and returns an ID token whose claims are renewed. |
tokens-per-audience | A token for each of auth-service, the gateway and your app, each with the right aud, azp and scope. |
bearer-own-resource | createBearerVerifier accepts a token minted for your own audience. |
introspection | auth.introspect reports the access token as active. |
wallet | Account, 7-day statistics, transactions, top-up options and the top-up URL. |
gateway-models, gateway-agents, gateway-mcp-servers | The listings, and mcpUrl(). |
chat-free-model | A chat call, with metadata.session_id. Needs a model whose id matches lagarde in the user's plan. |
embedding-billed-model | An embeddings call and the wallet debit it causes. Needs a model matching pplx-embed. |
wallet-session-usage | getSessionUsage for the session_id used above, polled until the call appears. |
machine-token | A client_credentials token for the application. |
billing-subscription | Subscription, usage and invoices through machine.billing. |
consumption | A report with an idempotency key, read back with machine.consumption.get. |
consumption-metered-feature | A report on the first metered feature of the plan, and the usage it changes. |
The model-dependent checks fail with no model matching … when the user's plan does not include such models: that is a property of your gateway setup, not an SDK problem.
The page also has buttons for the individual calls: gateway listings, a chat, an embedding, and a consumption report. The browser receives only the error codes of the self-test; the detailed report stays in the server log.
Bearer check
GET /api/bearer verifies an Authorization: Bearer token for the app's own audience and answers 401 with a WWW-Authenticate challenge pointing at /.well-known/oauth-protected-resource. It shows the pattern from Protect an API.