CIRCLE
Reference

Configuration

Every option of createAuthClient, createAuthHandlers and the other clients, with defaults and validation rules.

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.

OptionTypeDefaultDescription
issuerstringrequiredauth-service URL. HTTPS only (no loopback exception) and no trailing slash: it is compared verbatim to the iss claim, and discovery starts from it.
clientIdstringrequiredThe application's OAuth client id (its slug). Non-empty.
clientSecretstringnoneAbsent 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.
redirectUristringrequiredThe callback URL registered in auth-service. HTTPS, or HTTP for localhost, 127.0.0.1 and [::1] only.
postLogoutRedirectUristringnoneSent as post_logout_redirect_uri by logoutUrl(). Same URL rules as redirectUri.
scopesstring[]DEFAULT_SCOPESMust include openid.
resourcesstring[][]RFC 8707 audiences requested at sign-in, each a URL. Every refresh can narrow to one.
gatewayUrlstringnonePublic URL of the LiteLLM gateway. HTTPS (or loopback HTTP), no trailing slash. Turns on the gateway and wallet audiences.
clockToleranceSecondsinteger5Allowed clock skew when verifying tokens. From 0 to 300.
timeoutMsinteger10000Timeout 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

OptionTypeDescription
fetchtypeof fetchReplaces 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.

OptionTypeDefaultDescription
authAuthClientrequiredThe OIDC client.
grantsGrantManagerrequiredStores the refresh token obtained at sign-in.
sessionsSessionStorerequiredWhere sessions live. Use a database in production.
secretstringrequiredAt least 32 random characters. Seals the sign-in cookie. Keep it out of source control.
basePathstring"/auth"Prefix of the routes. Must match ^/[A-Za-z0-9/_-]*$ and not end with /. redirectUri must end with <basePath>/callback.
defaultRedirectstring"/"Where users land after sign-in or sign-out without a target.
sessionTtlSecondsnumber28800 (8 h)Absolute lifetime of a session. Capped at the ID token's exp when no refresh token was issued.
claimsRenewSecondsnumber900How often claims are renewed from the provider.
requireProviderSessionbooleantrueRefuse an ID token without sid.
errorRedirectstringnoneRedirect target of a failed sign-in, with ?error=<code>. JSON 403 when unset.
aiAiClientnoneAdds the /wallet, /wallet/stats and /models routes.
replayStoreReplayStoreMemoryReplayStoreRemembers accepted logout tokens. Share it across replicas.
onSessionsEnded(sessions: readonly Session[]) => Promise<void> | voidnoneCalled after sessions end (sign-out or back-channel logout).
onError(error: unknown) => voidnoneReceives unexpected failures and the ones the response must not detail.

Other constructors

ConstructorOptionsNotes
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.

Copyright © 2026