Register the application
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.
The registration is the same as for the TypeScript SDK: only the option names change (redirect_uri instead of redirectUri).
Checklist
| Setting in auth-service | Value | Why |
|---|---|---|
| Client type | Confidential, with a client secret | The SDK authenticates at the token endpoint with the secret, and the machine API needs it. Without client_secret the SDK acts as a public client that relies on PKCE alone. |
| Redirect URI | <origin><base_path>/callback | AuthHandlers verifies that the path of redirect_uri is <base_path>/callback. |
| Post-logout redirect URI | <origin><base_path>/logout/callback | The provider returns there after RP-initiated logout. AuthHandlers serves the route; pass the same URL as post_logout_redirect_uri. |
| Allow RP-Initiated Logout | On | /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><base_path>/backchannel-logout | HTTPS, reachable by auth-service. Signing out elsewhere then ends your local sessions. |
| Scopes | openid, profile, email, roles, permissions, features, offline_access | The SDK requests these by default (DEFAULT_SCOPES). A claim is only present when its scope is granted. |
| LiteLLM support | On, when you set gateway_url | Authorises the wallet:self:read scope and the gateway and auth-service audiences. |
| Machine scopes | billing:read, consumption:read, consumption:write | Needed by the machine API. |
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 require_provider_session=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 gateway_url in the AuthClient configuration. The switch authorises what the SDK then asks for at sign-in:
- the scope
wallet:self:read(the constantWALLET_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.