Configure an application
An application registration tells your tenant which client is signing someone in, where it can send the browser afterward, and which token behavior to use. Configure it in your tenant's Applications page. Start with the first-sign-in guide if you have not connected an app yet.
Keep environments separate
Register development and production as separate applications with different client credentials. For stronger separation of user data and sign-in policy, use separate tenants as well: changing the application environment does not create a separate user directory.
Use Development for local web callbacks such as
http://localhost:8000/auth/callback. Use Production with exact HTTPS web
callbacks. Development wildcard patterns are not allowed in production.
Native-app loopback IP callbacks and custom schemes have different rules from a hosted web callback. For a web project, use an exact HTTPS address in production instead of relying on a native-client exception.
Choose the client type
| Your application | Client configuration | Where credentials live |
|---|---|---|
| Web app with a backend or BFF | Confidential | Client secret and tokens on the backend |
| Browser-only app or installed native app | Public | No client secret; code shipped to users cannot keep one |
| Background service | Separate machine application | Server-side credentials; requires an application owner and permitted scopes |
For a browser app with a backend, use the confidential BFF path even if the UI is a React SPA. The backend is the OAuth2 client in this design.
Machine applications cannot combine Client Credentials with Authorization Code. The dashboard registration form cannot currently assign the machine application's owner. Coordinate that configuration through your beta setup; selecting the grant alone does not produce a working machine integration.
Register the callback exactly
The redirect URI is the endpoint in your app that finishes the login, such
as https://app.example.com/auth/callback. It is different from the callback
you register at a social provider, which returns to the identity service.
Check the scheme, hostname, port, path, and query. A callback configured on
localhost is not the same address as one configured on 127.0.0.1. A change
to your reverse proxy, preview URL, or auth mount may require updating both the
registration and your backend configuration.
Use an application-controlled return path after the callback. Do not accept arbitrary external redirect destinations from a browser parameter.
Select grants and identity scopes
For browser sign-in with session renewal, select Authorization Code and Refresh Token. Keep PKCE and state validation enabled in the client.
Request openid for OIDC sign-in, profile for supported profile claims, and
email when your application needs the address or verification status. Read
those claims from UserInfo when needed; do not assume the access token is a
complete user profile.
OAuth2 scopes and your application's permissions answer different
questions. A scope limits what a token can request. An application permission
describes what this user may do, such as projects:archive. Register and assign
those capabilities through permissions and roles, and enforce
them on the backend.
Choose how your API validates tokens
| Format | Validation | Revocation and permission freshness |
|---|---|---|
| Opaque | Ask the issuer's introspection endpoint | The service checks live token state; caching your own introspection result delays that observation |
| JWT | Verify signature, issuer, audience, and expiry using JWKS | Offline verification observes the token's issued claims until expiry; use an online check where you need current state |
For JWT access tokens, configure the intended API audience. Leaving it blank
uses the client ID. Your API must reject a token intended for another audience.
Hosted introspection requires a confidential application's credentials and only
answers for tokens issued to that application. Public client IDs and another
application's credentials receive { "active": false }, including for refresh
tokens. A separate API serving public or multiple client applications should use
JWT access tokens with its explicit API audience; registering a confidential
client alone does not grant cross-application introspection access.
See Protect an API for the checked implementation of each mode.
Create and rotate secrets
After saving a confidential client, open its detail page and choose Create new secret. Copy the one-time value into the backend secret manager. If the action is unavailable, your tenant access must include secret management.
For a rotation, create a replacement, deploy it to all application instances, verify a new login and refresh, and then revoke the previous secret. Coordinate the overlap with your deployment; deleting the old value before every instance has moved can interrupt authentication.
Next: learn the identity concepts, or use troubleshooting to diagnose an integration failure.
Last verified 2026-09-07.