CIRCLE
Getting started

Register the application

What to configure in auth-service before the SDK can sign users in: URIs, logout, LiteLLM support and machine scopes.

The SDK is only half of the setup. An administrator of auth-service registers your application once; the values below must match what you pass to the SDK. The registration itself is documented in auth-service: Managing applications and Integrating a third-party application.

Checklist

Setting in auth-serviceValueWhy
Client typeConfidential, with a client secretThe SDK authenticates at the token endpoint with the secret, and the machine API needs it. Without clientSecret the SDK acts as a public client that relies on PKCE alone.
Redirect URI<origin><basePath>/callbackThe sign-in handlers verify that redirectUri ends with <basePath>/callback.
Post-logout redirect URI<origin><basePath>/logout/callbackThe SDK serves this route to finish RP-initiated logout. Pass the same absolute URL as postLogoutRedirectUri.
Allow RP-Initiated LogoutOn/logout then also ends the provider's single sign-on session. Without an end_session_endpoint the local session still ends, but the provider session stays open.
Back-channel logout URI<origin><basePath>/backchannel-logoutHTTPS, reachable by auth-service. Signing out elsewhere then ends your local sessions.
Scopesopenid, profile, email, roles, permissions, features, offline_accessThe SDK requests these by default. A claim is only present when its scope is granted.
LiteLLM supportOn, when you set gatewayUrlAuthorises the wallet:self:read scope and the gateway and auth-service audiences.
Machine scopesbilling:read, consumption:read, consumption:writeNeeded by the machine API.
The sign-in refuses an ID token without a sid claim, because no back-channel logout could ever reach such a session. auth-service adds sid when end-session is enabled or a back-channel logout URI is set, so enable at least one of them. You can lift the check with requireProviderSession: false, at the price of sessions that never end on a provider-side logout.

LiteLLM support

When your application calls the gateway, switch on LiteLLM support for it in auth-service and pass the same gateway URL as gatewayUrl to createAuthClient. The switch authorises what the SDK then asks for at sign-in:

  • the scope wallet:self:read (the constant WALLET_SELF_SCOPE),
  • the gateway URL as a resource (audience), and
  • the auth-service URL (your issuer) as a resource, because auth-service serves the wallet.

See Credit wallet and LiteLLM gateway for how these pieces fit together, and the auth-service guide LiteLLM gateway and credit wallet in an application for the operator side (plans, access groups, budgets).

Machine scopes

A new confidential application receives billing:read, consumption:read and consumption:write by default. An application created before that default existed needs them set by a superadmin; until then the machine API fails with TOK_004 (the token endpoint answers invalid_scope). See Machine scopes in the auth-service documentation.

Your own API as a resource

If you protect your own API with Bearer tokens, list its URL in resources so that sign-in also requests an access token for it, and make sure auth-service allows the application to request it. Auth-service rejects unknown or unlinked resources with invalid_target.

Secrets

The SDK reads no environment variable itself: you pass every value to it. Keep the client secret and the cookie secret in your own configuration (environment variables, a secret manager), never in source control. The documentation uses placeholders such as AUTH_CLIENT_SECRET and AUTH_COOKIE_SECRET for that.

Copyright © 2026