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:
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:
- 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.
- Access Token Exchange (server-to-server) — Your server exchanges the authorization code for an access token.
- 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 thecode_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-xxxxxxxxxxxxOnce the access token expires, repeat Steps 1–3 to obtain a new one.