Configuration
The SDK reads no environment variable: every value is passed in code. Validation happens when the object is created, and an invalid configuration throws CFG_001 (see Error codes) with the offending paths in the message.
createAuthClient(config, options?)
Returns an AuthClient, the OIDC relying party. The config is validated with zod; AuthClientConfig is the input type and ResolvedAuthClientConfig (available as auth.config) the output type.
| Option | Type | Default | Description |
|---|---|---|---|
issuer | string | required | auth-service URL. HTTPS only (no loopback exception) and no trailing slash: it is compared verbatim to the iss claim, and discovery starts from it. |
clientId | string | required | The application's OAuth client id (its slug). Non-empty. |
clientSecret | string | none | Absent for a public client, which then relies on PKCE alone. Needed by clientCredentials and the machine API. |
tokenEndpointAuthMethod | "client_secret_basic" | "client_secret_post" | "client_secret_basic" | How the secret is sent to the token endpoint. Ignored without a clientSecret. |
redirectUri | string | required | The callback URL registered in auth-service. HTTPS, or HTTP for localhost, 127.0.0.1 and [::1] only. |
postLogoutRedirectUri | string | none | Sent as post_logout_redirect_uri by logoutUrl(). Same URL rules as redirectUri. |
scopes | string[] | DEFAULT_SCOPES | Must include openid. |
resources | string[] | [] | RFC 8707 audiences requested at sign-in, each a URL. Every refresh can narrow to one. |
gatewayUrl | string | none | Public URL of the LiteLLM gateway. HTTPS (or loopback HTTP), no trailing slash. Turns on the gateway and wallet audiences. |
clockToleranceSeconds | integer | 5 | Allowed clock skew when verifying tokens. From 0 to 300. |
timeoutMs | integer | 10000 | Timeout of discovery, JWKS and API requests. Positive. |
DEFAULT_SCOPES is openid, profile, email, roles, permissions, features, offline_access.
With gatewayUrl, the resolved config adds wallet:self:read (exported as WALLET_SELF_SCOPE) to scopes, and the gateway URL and the issuer to resources, without duplicates.
import { createAuthClient } from "@circle-rd/auth-ai";
const auth = createAuthClient({
issuer: "https://auth.example.com",
clientId: "my-app",
clientSecret: "<client-secret>",
redirectUri: "https://app.example.com/auth/callback",
postLogoutRedirectUri: "https://app.example.com/auth/logout/callback",
gatewayUrl: "https://llm.example.com",
resources: ["https://app.example.com"],
});
console.log(auth.config.scopes.at(-1)); // "wallet:self:read"
AuthClientOptions
| Option | Type | Description |
|---|---|---|
fetch | typeof fetch | Replaces the global fetch for every request, including the REST API clients built on this client: use it for a proxy or an observability layer. |
createAuthHandlers(options)
Returns Promise<AuthHandlers>. Details of the routes are in Web handlers and Fastify.
| Option | Type | Default | Description |
|---|---|---|---|
auth | AuthClient | required | The OIDC client. |
grants | GrantManager | required | Stores the refresh token obtained at sign-in. |
sessions | SessionStore | required | Where sessions live. Use a database in production. |
secret | string | required | At least 32 random characters. Seals the sign-in cookie. Keep it out of source control. |
basePath | string | "/auth" | Prefix of the routes. Must match ^/[A-Za-z0-9/_-]*$ and not end with /. redirectUri must end with <basePath>/callback. |
defaultRedirect | string | "/" | Where users land after sign-in or sign-out without a target. |
sessionTtlSeconds | number | 28800 (8 h) | Absolute lifetime of a session. Capped at the ID token's exp when no refresh token was issued. |
claimsRenewSeconds | number | 900 | How often claims are renewed from the provider. |
requireProviderSession | boolean | true | Refuse an ID token without sid. |
errorRedirect | string | none | Redirect target of a failed sign-in, with ?error=<code>. JSON 403 when unset. |
ai | AiClient | none | Adds the /wallet, /wallet/stats and /models routes. |
replayStore | ReplayStore | MemoryReplayStore | Remembers accepted logout tokens. Share it across replicas. |
onSessionsEnded | (sessions: readonly Session[]) => Promise<void> | void | none | Called after sessions end (sign-out or back-channel logout). |
onError | (error: unknown) => void | none | Receives unexpected failures and the ones the response must not detail. |
Other constructors
| Constructor | Options | Notes |
|---|---|---|
new GrantManager({ auth, store, lock?, expirySkewSeconds? }) or createGrantManager(...) | auth needs refresh and revoke; lock defaults to InProcessGrantLock; expirySkewSeconds defaults to 30. | See Sessions and grants. |
createAiClient({ auth, grants }) | auth needs config and fetch; grants needs getAccessToken and invalidate. | forUser(grantId) returns a UserAi with wallet and gateway. |
createMachineApi(auth) | auth needs clientCredentials, config and fetch. | Throws CFG_001 without a clientSecret. |
createBearerVerifier(auth, { audience }) | audience must be a URL. | Throws CFG_001 otherwise. |
createBackchannelLogoutHandler({ auth, onLogout, replayStore?, onError? }) | replayStore defaults to MemoryReplayStore. | For use without the sign-in handlers. |
createBrowserAuth({ basePath?, fetch?, location? }) | basePath defaults to "/auth". | See Browser, React and Vue. |
new GatewayClient({ gatewayUrl, tokens, fetch, timeoutMs }) is exported, but you normally get one from ai.forUser(id).gateway, which wires the tokens for you. WalletClient is exported too, but its constructor takes an internal HTTP helper that the package does not export: get it from ai.forUser(id).wallet.
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.
Core API
Reference of the main entry point, @circle-rd/auth-ai: AuthClient, GrantManager, AiClient, WalletClient, GatewayClient, claims helpers and the error registry.