CIRCLE
Operations

Example app

Run examples/minimal, a Fastify backend and vanilla page that exercise every part of the SDK against a real auth-service, with a built-in self-test.

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

FileRole
server/main.tsThe Fastify backend: createAuthClient, GrantManager, createAiClient, createMachineApi, createAuthHandlers, authPlugin, the protected routes, a Bearer-protected route and the protected-resource metadata.
server/config.tsReads and validates the environment; names the offending variables, never their values.
server/selftest.tsThe self-test: sixteen checks that run for the signed-in user.
web/A vanilla TypeScript page using @circle-rd/auth-ai/client.
Dockerfile, compose.ymlBuild 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/callback and post-logout URI https://<host>/.
  • Back-channel logout URI https://<host>/auth/backchannel-logout.
  • Machine scopes billing:read, consumption:read and consumption: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:

VariableDefaultDescription
PORT3000Listening port.
PUBLIC_URLrequiredPublic URL of the app, for example https://test.example.com.
AUTH_ISSUERrequiredauth-service URL.
AUTH_CLIENT_IDrequiredThe application's client id.
AUTH_CLIENT_SECRETrequiredThe client secret. A secret: never commit it.
GATEWAY_URLrequiredThe LiteLLM gateway URL.
COOKIE_SECRETrequiredAt 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 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 these checks for your user and logs a report that holds no token or secret:

CheckWhat it verifies
session-claimsThe session carries sid, roles, permissions, features, plan and organisation.
refresh-returns-id-tokenA refresh rotates the token and returns an ID token whose claims are renewed.
tokens-per-audienceA token for each of auth-service, the gateway and your app, each with the right aud, azp and scope.
bearer-own-resourcecreateBearerVerifier accepts a token minted for your own audience.
introspectionauth.introspect reports the access token as active.
walletAccount, 7-day statistics, transactions, top-up options and the top-up URL.
gateway-models, gateway-agents, gateway-mcp-serversThe listings, and mcpUrl().
chat-free-modelA chat call, with metadata.session_id. Needs a model whose id matches lagarde in the user's plan.
embedding-billed-modelAn embeddings call and the wallet debit it causes. Needs a model matching pplx-embed.
wallet-session-usagegetSessionUsage for the session_id used above, polled until the call appears.
machine-tokenA client_credentials token for the application.
billing-subscriptionSubscription, usage and invoices through machine.billing.
consumptionA report with an idempotency key, read back with machine.consumption.get.
consumption-metered-featureA 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.

Copyright © 2026