Getting Started

Quick Start Guide

The shortest safe path from client registration to a working OAuth integration.

API Version

5.29.0

Recommended path

Use OAuth 2.0 Authorization Code flow. Do not treat the public password-login endpoint as a replacement for OAuth token issuance.

If you are implementing login screens, auth forms, or app UI around this flow, follow the shared General Design System as the authoritative cross-project design system.

1. Register Your OAuth Client

Create an OAuth client in the SSO admin UI and store:

SSO_CLIENT_ID=your-client-id
SSO_CLIENT_SECRET=your-client-secret
SSO_REDIRECT_URI=https://yourapp.com/auth/callback

2. Redirect to Authorization

GET /api/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/auth/callback
  &response_type=code
  &scope=openid%20profile%20email%20offline_access
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Users can authenticate there with password, magic link, PIN, Google, or Facebook.

3. Exchange the Code Server-Side

POST /api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://yourapp.com/auth/callback",
  "code_verifier": "PKCE_VERIFIER"
}

4. Use Tokens Correctly

Use id_token for identity claims.
Use access_token for SSO API authorization.
Refresh expired access tokens with grant_type=refresh_token.

5. Check App Permission State

Authentication alone is not enough for per-app access. Check or manage permission state with the relevant permission endpoints.