CIRCLE auth-ai
A TypeScript SDK for applications that sign their users in through a CIRCLE auth-service. Run the OIDC flow on your backend, keep tokens off the browser, read roles and plan features, and let users call LLMs through the LiteLLM gateway against their credit wallet.
What it does
Backend-for-frontend sign-in
Authorization code flow with PKCE on your server. The browser only holds an opaque, HttpOnly session cookie: access and refresh tokens never reach it.
Grants and per-audience tokens
One refresh-token chain per user, rotated under a lock, and short-lived access tokens minted per audience (RFC 8707) for your API, the gateway and auth-service.
Entitlements from claims
Roles, permissions, plan features and organisation are read from the ID token and renewed from the provider on a schedule. hasRole, hasPermission, hasFeature and getFeature work on both sides.
Back-channel logout
OIDC Back-Channel Logout verified and replay-protected: signing out of auth-service ends your local sessions and revokes the grant.
Credit wallet and LiteLLM gateway
Read the user's prepaid balance and spend, and call an OpenAI-compatible gateway with the user's own token. The gateway debits the wallet; your app never handles a debit.
Billing and consumption
From your backend with a machine token: read a user's subscription, metered usage and invoices, and report consumption with idempotency keys.
Protect an API
Verify JWT Bearer tokens for your own audience, require scopes, and publish RFC 9728 protected-resource metadata so MCP and OAuth clients can discover the provider.
Fastify, React, Vue
A Fastify plugin, Web-standard handlers for any other framework, a framework-agnostic browser client, and React and Vue bindings.
Errors safe to show
Every failure is an AuthAiError with a stable code. Details stay in your logs; HTTP responses carry the code and a generic message only.