Build an OAuth application

OAuth applications let an organization administrator authorize a third-party product without sharing a service-account token. RIIW supports Authorization Code with mandatory PKCE S256; implicit flow, client credentials, dynamic registration, and password grants are not supported.

Register an application

1. Open your profile menu and select Developer Settings.
2. Enter an application name, exact redirect URI, and requested Public API scopes.
3. Create the draft and copy its public client_id.
4. Keep the application in draft while testing it in an organization you own.
5. Submit it for review only when redirect URIs, scopes, support information, privacy information, and production behavior are ready.

Localhost redirect URIs are allowed during non-production development. Production redirect URIs must use HTTPS, must match exactly, and cannot contain fragments. The OAuth application is public and has no client secret; PKCE protects authorization-code exchange.

Start authorization

Generate a cryptographically random state and PKCE verifier in the third-party application. Store them in a short-lived, server-controlled session. Send the SHA-256 base64url challenge to /oauth2/authorize with:

• response_type=code
• the registered client_id and exact redirect_uri
• organization_id for the organization being authorized
• requested scope, including openid and optionally offline_access
• code_challenge and code_challenge_method=S256
• the random state

The signed-in organization owner, admin, or role with OAuth approval capability sees the RIIW consent page. Chat scopes require selected active organization channels or explicit access to all current and future organization channels. Direct messages cannot be selected.

After the user approves, validate state at the redirect URI and exchange the one-time code at /oauth2/token with the original verifier. Access tokens last 60 minutes. Refresh tokens rotate, expire after 30 days of inactivity, and cannot outlive the 180-day grant lifetime. Persist the newest refresh token atomically and discard the replaced value.

Understand application status

Creating a custom OAuth app does not authorize it for an organization. After an eligible administrator completes consent, it appears in the selected organization's Apps area. Owners manage the grant from protected Apps & integrations settings. See Manage organization apps for the organization-side view.

Production checklist

• Validate state and PKCE on every authorization.
• Request minimal scopes and explain why each is needed.
• Store rotating refresh tokens encrypted and never expose them to browser logs.
• Handle denial, expired codes, suspended apps, revoked installations, and temporary integration pauses.
• Provide users with a clear disconnect action that calls /oauth2/revoke and directs organization administrators to revoke the installation when necessary.
• Never retry a code exchange with a different verifier.

Use the discovery document at /.well-known/openid-configuration to obtain current OAuth endpoints and signing metadata instead of hard-coding issuer details beyond your trusted environment configuration.