Call Your API Using the Authorization Code Flow with PKCE

This guide demonstrates how to call your API from native, mobile, or single-page applications (SPAs) using the Authorization Code Flow with Proof Key for Code Exchange (PKCE). For a detailed explanation of PKCE, refer to Authorization Code Flow with PKCE in Login 3.0.

---

Implementation Overview

• Use the PKCE flow for applications that cannot securely store a client secret.

• Retrieve:

  • An Authorization Code for exchanging tokens.

  • An Access Token to access APIs securely.

  • Optionally, a Refresh Token for session continuity.

---

Prerequisites

Before you begin:

1. Register Your Application:

   • Choose the appropriate type (Native or SPA).

   • Add an allowed callback URL (e.g., https://yourCallbackUrl).

   • Ensure grant types include authorization_code and, optionally, refresh_token.

2. Register Your API (if applicable):

   • Define required scopes and permissions.

   • Configure token expiration and access settings.

3. Enable Offline Access (optional):

   • Allow your application to request and use refresh tokens.

The UPBOND team will assist in configuring your Login 3.0 tenant and API settings.

---

Steps

1. Create Code Verifier

Generate a code_verifier, a random Base64-encoded string used for token exchange.

JavaScript Example:

function base64URLEncode(str) {
    return str.toString('base64')
        .replace(/\\+/g, '-')
        .replace(/\\//g, '_')
        .replace(/=/g, '');
}
const verifier = base64URLEncode(crypto.randomBytes(32));

---

2. Create Code Challenge

Hash the code_verifier using SHA-256 and Base64 encode the result.

JavaScript Example:

function sha256(buffer) {
    return crypto.createHash('sha256').update(buffer).digest();
}
const challenge = base64URLEncode(sha256(verifier));

---

3. Authorize User

Redirect the user to the Login 3.0 authorization endpoint with the code_challenge:

Authorization URL Example:

https://{yourDomain}/authorize?
  response_type=code&
  client_id={yourClientId}&
  code_challenge={codeChallenge}&
  code_challenge_method=S256&
  redirect_uri={yourCallbackUrl}&
  scope=openid%20profile%20email&
  audience={yourApiAudience}&
  state=xyzABC123

Replace placeholders with your app's specific details.

---

4. Request Tokens

Exchange the authorization_code and code_verifier for tokens.

Token Request Example:

curl --request POST \\
  --url 'https://{yourDomain}/oauth/token' \\
  --header 'content-type: application/x-www-form-urlencoded' \\
  --data grant_type=authorization_code \\
  --data 'client_id={yourClientId}' \\
  --data 'code_verifier={yourCodeVerifier}' \\
  --data 'code={authorizationCode}' \\
  --data 'redirect_uri={yourCallbackUrl}'

Response:

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in": 86400
}

---

5. Call Your API

Use the Access Token to make API requests:

curl --request GET \\
  --url 'https://{yourApi}/endpoint' \\
  --header 'Authorization: Bearer {accessToken}'

---

6. Refresh Tokens (Optional)

Use the refresh token to obtain new tokens without user interaction.

Request Example:

curl --request POST \\
  --url 'https://{yourDomain}/oauth/token' \\
  --header 'content-type: application/x-www-form-urlencoded' \\
  --data grant_type=refresh_token \\
  --data 'client_id={yourClientId}' \\
  --data 'refresh_token={yourRefreshToken}'

---