Choose an OAuth grant and application type

Application type and OAuth grant determine where credentials can be protected and how a user or service authorizes access. Configure only flows that the client can implement securely.

The released application contract supports application types web, spa, mobile, desktop, and service-to-service, with authorization code, client credentials, refresh token, and Device Code grants where configured.

Web applications

Choose web for server-backed browser applications that can keep confidential credentials and exchange authorization codes on a trusted backend.

Use:

• authorization code for user sign-in/consent;
• exact HTTPS redirect URIs;
• refresh tokens only when durable user access is required;
• server-side token and secret storage.

Do not expose a client secret in rendered HTML or browser JavaScript.

Single-page applications

Choose spa for browser-only clients. A SPA cannot safely hold a long-lived client secret.

• Treat it as a public client.
• Use the supported authorization-code pattern and browser protections exposed by the platform.
• Register exact origins and redirect URIs.
• Keep access tokens short-lived and avoid persistent broad tokens.
• Do not enable client credentials for a browser bundle.

Review the deployed connection contract before implementing; do not invent a token flow from application metadata alone.

Mobile and desktop applications

Choose mobile or desktop for installed clients. Installed binaries cannot guarantee secrecy of embedded credentials.

Use a public-client flow supported by the application. Authorization code can work with platform-safe callbacks; Device Code is useful when browser callback handling is difficult or the input device is constrained.

Never ship a reusable confidential secret inside an app package.

Service-to-service applications

Choose service-to-service for trusted backend automation without an interactive user.

Client credentials may be appropriate when released and configured for the application. Keep credentials in a secret manager, scope permissions narrowly, rotate them, and separate development from production.

Do not use client credentials to impersonate end users or bypass workspace membership.

Authorization Code grant

Use authorization code when a user should sign in and consent.

client → authorization page → user approval → exact redirect with code → trusted exchange → tokens

Security requirements:

• exact registered redirect URIs;
• state/session binding;
• supported proof/key protections for public clients;
• one-time, short-lived codes;
• server-side exchange for confidential clients;
• no credentials in logs or URLs beyond protocol-required temporary values.

Refresh Token grant

Enable refresh tokens only when the application must continue after the access token expires.

• Request only needed offline access.
• Store refresh tokens more securely than ordinary session data.
• Prefer rotation where configured.
• Detect reuse and revoke on compromise.
• Expire sessions that are no longer active.
• Do not issue long-lived access merely for developer convenience.

Client Credentials grant

Use client credentials for non-interactive trusted services. There is no user consent step in each request, so application configuration and service credential custody are critical.

Never enable it for SPA, mobile, desktop, CLI, or other distributed public clients.

Device Authorization Grant

Usable supports RFC 8628 Device Code for applications where configured. It separates the input-constrained client from browser authorization:

device requests code → user opens verification URL → user enters code and approves → device polls → tokens

The device must:

• display the verification URL and user code clearly;
• treat the code as short-lived and sensitive;
• poll only at the instructed interval;
• handle authorization pending, slow-down, denial, and expiry;
• stop polling after success or terminal failure;
• avoid displaying client secrets.

Usable v1.187.1 fixed device auth so supported token updates work as expected. Clients must still verify the deployed version and final token state.

Redirect URIs and allowed origins

• Use exact HTTPS URIs in production.
• Separate development, preview, and production registrations.
• Avoid wildcards and open redirect endpoints.
• Do not register private/internal hosts for public apps.
• Remove obsolete callbacks.
• Validate environment before exchanging a code.

Allowed browser origins are not redirect URIs and do not replace authorization checks.

Selection checklist

1. Can the client keep a secret?
2. Is a user present to consent?
3. Is a browser redirect practical?
4. Is offline access truly needed?
5. Is the device input-constrained?
6. What workspace and permission scope is necessary?
7. How will tokens be rotated and revoked?
8. Which environment owns each redirect and credential?

Enable the minimum set of grants that answers these needs.

Related pages

• Create and manage an application
• Configure permissions, access, and token security
• Authenticate and authorize API requests