CIRCLE
Getting started

Introduction

What CIRCLE auth-ai is, when to use it, and how it fits between your application and auth-service.

@circle-rd/auth-ai is a TypeScript SDK for applications that sign their users in through a CIRCLE auth-service instance. It covers the application side of the relationship: the OIDC sign-in, the session, the user's entitlements, the credit wallet, the LiteLLM gateway, and the machine-to-machine billing and consumption APIs.

The SDK is a 0.x release: the public API is not stable yet. See Release channels.
Building a Python backend? Use the Python SDK: same behaviours, same wire contract, and it works with this package's browser client and React and Vue bindings.

When to use it

Use auth-ai when your application:

  • signs users in with an auth-service instance and wants a server-side session instead of tokens in the browser;
  • reads roles, permissions, plan features or the organisation from the user's claims;
  • lets users call LLMs or MCP tools through the LiteLLM gateway and bills their credit wallet;
  • reports consumption or reads a user's subscription and invoices from its backend;
  • exposes its own API protected by auth-service Bearer tokens.

It is built for auth-service, whose claims and wallet, billing and consumption REST routes it relies on. It is not a client for arbitrary OIDC providers and it is not an identity provider: to run the provider, see the auth-service documentation.

How it fits

Browser ──── session cookie (opaque, HttpOnly) ───▶ Your backend
                                                       │  @circle-rd/auth-ai
                      OIDC code + PKCE, refresh,       │
                      client_credentials, wallet       ▼
                                                  auth-service
                                                       │ access token (audience = gateway)
                                                       ▼
                                                 LiteLLM gateway ── debits the user's wallet

The browser never holds a token. Your backend holds one refresh-token chain per user and mints short-lived access tokens for each audience it needs. Read Architecture for the details.

What is in the box

Entry pointUse it for
@circle-rd/auth-aiThe core: createAuthClient, GrantManager, createAiClient, claims helpers, formatEuros, the error registry. It uses Web-standard APIs only (fetch, Request, Web Crypto).
@circle-rd/auth-ai/webBackend-for-frontend sign-in handlers (createAuthHandlers) and the session store.
@circle-rd/auth-ai/fastifyA Fastify plugin and pre-handlers on top of the web handlers.
@circle-rd/auth-ai/serverBearer token verification, back-channel logout, protected-resource metadata, and the billing and consumption API.
@circle-rd/auth-ai/clientThe browser client and framework-agnostic stores. Pulls no server code.
@circle-rd/auth-ai/reactAuthProvider and hooks.
@circle-rd/auth-ai/vuecreateAuthPlugin and composables.

Next steps

  1. Install the package.
  2. Register your application in auth-service.
  3. Follow the Quick start to get a sign-in running.
Copyright © 2026