A Singapore Government Agency Website

Consuming an OAuth 2.1-protected API

OAuth 2.1 is used for APIs that require explicit user consent — for example, APIs that access a Corppass user’s data on their behalf. Unlike API Key or JWT auth, the user must actively log in and authorize your application before you can make API calls on their behalf.

Before continuing, ensure you have:

  1. Created an application
  2. Generated an API key
  3. Subscribed to the OAuth 2.1-protected API
  4. Registered an OAuth client
  5. Configured OAuth scopes

Prefer to follow along visually? The OAuth 2.1 interactive walkthrough covers the whole setup in five short demos, from understanding an OAuth API to calling it with an access token.

Overview of the flow

The OAuth 2.1 Authorization Code Flow with PKCE consists of three stages:

  1. Authorization Grant (browser) — Redirect the user to APEX, they log in with Corppass and grant consent, and your app receives a short-lived authorization code.
  2. Access Token Exchange (server-to-server) — Your server exchanges the authorization code for an access token.
  3. API Call — Use the access token to call the protected API.

Endpoints

IDP Environment Authorize endpoint Token endpoint
Corppass Sandbox https://sandbox.api.gov.sg/oauth/cp/v3/authorize https://sandbox.api.gov.sg/oauth/cp/v3/token
Corppass Production https://public.api.gov.sg/oauth/cp/v3/authorize https://public.api.gov.sg/oauth/cp/v3/token
Singpass Sandbox https://sandbox.api.gov.sg/oauth/sp/v3/authorize https://sandbox.api.gov.sg/oauth/sp/v3/token
Singpass Production https://public.api.gov.sg/oauth/sp/v3/authorize https://public.api.gov.sg/oauth/sp/v3/token

Step 1 — Generate PKCE values

PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks. Generate these two values before starting the flow:

  • code_verifier — a random URL-safe string, 43–128 characters long.
  • code_challenge — the Base64 URL-encoded SHA-256 hash of the code_verifier.

You will send the code_challenge in Step 2 and the code_verifier in Step 3.

  • code_verifier: owFWUGrbZ3Bk5epaumy2EYkMCQZnkjoL_H79Gv02u0
  • code_challenge: 3yj50_1LB91nSs9DyzZ5tPZh5H0NxWLwNtYBXOpOrII

Step 2 — Redirect the user to the Authorization Endpoint

Redirect the user’s browser to the authorize endpoint with the following parameters:

{Authorization Endpoint}
  ?client_id={client_id}
  &redirect_uri={redirect_uri}
  &response_type=code
  &scope={scope}
  &code_challenge_method=S256
  &code_challenge={code_challenge}
Parameter Description
client_id Your OAuth Client ID from the APEX Portal.
redirect_uri URL-encoded callback URL of your application.
response_type Must be code.
scope The scope(s) provided by the API publisher.
code_challenge_method Must be S256.
code_challenge Generated in Step 1.
state (Optional) A value used to maintain state between the request and callback, up to 200 characters.

The user will be presented with a Corppass login screen followed by a consent screen. After they authorize your application, APEX redirects them to your redirect_uri with an authorization code:

Example: https://your-app.example.com/callback?code=apex-cp-example-code-return

The authorization code is valid for 5 minutes. Exchange it immediately.

Step 3 — Exchange the Authorization Code for an Access Token

From your server, make a POST request to the token endpoint:

POST {Token Endpoint}
Content-Type: application/x-www-form-urlencoded

code={authorization_code}
&client_id={client_id}
&client_assertion={client_assertion}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&grant_type=authorization_code
&redirect_uri={redirect_uri}
&code_verifier={code_verifier}

The client_assertion is a JWT signed with your ES256 private key. It proves your server’s identity to APEX. Include these claims:

Claim Value
iss Your Client ID.
sub Your Client ID.
aud The Token Endpoint URL.
kid Key ID of the signing key in your JWKS.
jti A unique identifier for this token request.
iat Current Unix timestamp (seconds).
exp iat + 300 seconds (5 minutes).

A successful response returns an access token:

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "token_type": "Bearer",
  "expires_in": 1799,
  "scope": "ScopeA ScopeB"
}

The access token is valid for 30 minutes.

Step 4 — Call the API

Include both the access token and your API key in every request:

GET /agency/api
Host: public.api.gov.sg
Authorization: Bearer eyJ0eXAiOiJKV1Qi...
x-apex-apikey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Once the access token expires, repeat Steps 1–3 to obtain a new one.

Chat with me!
Bot Launcher