Skip to content

OAuth2 Authorization Code Flow

The Authorization Code flow is the standard OAuth2 flow for interactive users with browser access.

Overview

This flow:

  1. Opens a browser for user authentication
  2. Redirects back with an authorization code
  3. Exchanges the code for access and refresh tokens
sequenceDiagram
    participant User
    participant Client Package
    participant Browser
    participant IdP as Identity Provider

    User->>Client Package: Initiate login
    Client Package->>Browser: Open login URL
    Browser->>IdP: Navigate to login
    User->>IdP: Enter credentials
    IdP->>Browser: Redirect with code
    Browser->>Client Package: Authorization code
    Client Package->>IdP: Exchange code for tokens
    IdP->>Client Package: Access + Refresh tokens
    Client Package->>User: Login complete

Using with QLAM Shell

The simplest way to use this flow is through QLAM Shell:

qsh auth login

This handles the entire flow automatically:

  1. Opens your default browser to the login page
  2. Waits for authentication to complete
  3. Stores tokens in ~/.qsh/credentials/

Manual Implementation

If implementing the flow directly (not using QLAM Shell):

Step 1: Build Authorization URL

https://{auth_base_url}/authorize?
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}&
  scope={scope}&
  audience={audience}&
  state={random_state}

Parameters:

Parameter Description
response_type Always code for this flow
client_id Your OAuth2 client ID
redirect_uri Where to redirect after login
scope Requested permissions (e.g., openid email profile offline_access)
audience API identifier
state Random string for CSRF protection

Step 2: Handle Callback

After successful authentication, the user is redirected to your redirect_uri with:

{redirect_uri}?code={authorization_code}&state={state}

Verify that state matches what you sent.

Step 3: Exchange Code for Tokens

curl --request POST \
  --url "https://{auth_base_url}/oauth/token" \
  --header "content-type: application/x-www-form-urlencoded" \
  --data grant_type=authorization_code \
  --data "client_id={client_id}" \
  --data "code={authorization_code}" \
  --data "redirect_uri={redirect_uri}"

Step 4: Receive Tokens

Successful response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "v1.MSjO...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email offline_access"
}

Next Steps