Introduction
@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.
0.x release: the public API is not stable yet. See Release channels.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 point | Use it for |
|---|---|
@circle-rd/auth-ai | The core: createAuthClient, GrantManager, createAiClient, claims helpers, formatEuros, the error registry. It uses Web-standard APIs only (fetch, Request, Web Crypto). |
@circle-rd/auth-ai/web | Backend-for-frontend sign-in handlers (createAuthHandlers) and the session store. |
@circle-rd/auth-ai/fastify | A Fastify plugin and pre-handlers on top of the web handlers. |
@circle-rd/auth-ai/server | Bearer token verification, back-channel logout, protected-resource metadata, and the billing and consumption API. |
@circle-rd/auth-ai/client | The browser client and framework-agnostic stores. Pulls no server code. |
@circle-rd/auth-ai/react | AuthProvider and hooks. |
@circle-rd/auth-ai/vue | createAuthPlugin and composables. |
Next steps
- Install the package.
- Register your application in auth-service.
- Follow the Quick start to get a sign-in running.