# Integration Guide

This guide outlines the steps to integrate with Corppass Authorization API.

## Environments

Corppass provides separate environments for integration and testing (Staging) and live transactions (Production). Use the **Base URL** corresponding to the selected environment for all subsequent steps.

**Recommendation:** It is recommended to integrate and validate implementation against the Staging environment before switching to Production.

<table><thead><tr><th width="141.609375">Environment</th><th width="292.29296875">Base URL</th><th>Description</th></tr></thead><tbody><tr><td>Staging</td><td><code>https://stg-id.corppass.gov.sg</code></td><td>Used for <strong>development</strong>, <strong>integration testing</strong>, and <strong>pre-production</strong> validation.</td></tr><tr><td>Production</td><td><code>https://id.corppass.gov.sg</code></td><td>Live environment for <strong>real users and transactions</strong>. Must be used only after successful onboarding and certification.</td></tr></tbody></table>

## Steps

{% hint style="info" %}

#### Prerequisite: Client Application Registration

Before starting integration, create and configure your client application.

* **Corppass Login application**: Use the **Corppass Developer Portal (CDP)** to create your client application and obtain your Client ID. [Refer to getting started](/products/corppass-login/getting-started.md)
* **Myinfo Business application:** Use the Singpass Developer Portal (SDP) to create your client application and obtain your Client ID. [Refer to getting started](/products/myinfo-business/getting-started.md)
  {% endhint %}

{% hint style="info" %}

#### Implementation Notes

* **Certified Libraries:** As Corppass Authorization API is fully compliant with OIDC and FAPI 2.0, it is highly recommended to use a [Certified OIDC Relying Party Library](https://openid.net/developers/certified-openid-connect-implementations/). This simplifies development and ensures compliance.\
  If you opt to implement the protocol directly, we encourage you to validate your implementation using the [OIDC Conformance Tests](https://openid.net/certification/fapi_rp_testing/).
* **Dynamic Discovery:** Do not hardcode endpoint paths (e.g., `/token`). Always derive them from the Base URL using the [Discovery Endpoint](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/openid-discovery-endpoint.md).
* **TLS Certificates:** Do not implement certificate pinning nor have any dependencies on the TLS certifications for Corppass domains. **Corppass reserves the right to update or rotate its TLS certificates without prior notice.**
  {% endhint %}

### Overview

The following diagram illustrates the FAPI 2.0 Authorization Code Flow.

This flow requires a Confidential Client (Backend-for-Frontend) architecture.

* RP Client (FE): The browser / frontend handles user interaction and redirects.
* RP Server (BE): The backend maintains the secure session. All sensitive operations - including signing requests, handling DPoP keys, and token exchange - must occur on the backend to prevent credential leakage.

<div data-full-width="true"><figure><img src="/files/tG8HNNeqno4zzTt3lauA" alt=""><figcaption></figcaption></figure></div>

### 0. Configuration & Discovery

**Endpoint:** `/.well-known/openid-configuration` | [View Specification](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints.md)

**Access:** Public TLS

Once registered, programmatically discover Corppass's current configuration at runtime.

* **Fetch Metadata (Discovery Endpoint):** Initiate a request to the [OpenID Discovery Endpoint](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/openid-discovery-endpoint.md) to retrieve the provider configuration. This provides endpoint URLs, supported scopes, algorithms, and JWKS locations needed for the authorization flow.
* **Fetch Public Keys (JWKS Endpoint):** Using the `jwks_uri` found in the metadata, fetch and cache Corppass's public keys. These are required later to verify the signatures of the ID Token and UserInfo response.

### 1. Secured Request - Pushed Authorization Request (PAR)

**Endpoint:** `/request` | [View Specification](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/1.-pushed-authorization-request-par-endpoint.md)

**Access:** Public TLS with Client Assertion and DPoP

**Trigger:** Initiate this flow immediately when the user initiates login with Corppass.

Corppass FAPI 2.0 requires the Pushed Authorization Request (PAR) flow. Authorization parameters are "pushed" securely via a back-channel API call rather than being exposed in the browser URL.

* **Action:** Send a `POST` request to the PAR endpoint.
* **Result:** The response contains a short-lived **`request_uri`**, which is required for the subsequent Authorization Endpoint step.

### 2. User Authentication - Authorization Endpoint

**Endpoint:** `/authorize` | [View Specification](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/2.-authorization-endpoint.md)

**Access:** Public TLS (Browser Redirect)

Once the request payload is registered via PAR, redirect the user's browser to Corppass to perform the actual Singpass login and consent.

* **Action:** Redirect the user to the Authorization Endpoint with the `request_uri` obtained from PAR.
* **Result:** After successful authentication, the user agent is redirected to the client's redirect URI with an **Authorization Code**, which is required for the subsequent Token Exchange step.

### 3. Token Exchange - Token Endpoint

**Endpoint:** `/token` | [View Specification](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/3.-token-endpoint.md)

**Access:** Public TLS with Client Assertion and DPoP

This is a secure back-channel exchange where the Authorization Code is swapped for actual credentials (Tokens).

* **Action:** Send a `POST` request to the Token Endpoint, with the Authorization Code obtained from the authorization request.
* **Result:** The response contains:
  * **ID Token:** A signed and encrypted JWE that includes the entity and user information. Relying Parties (RPs) must decrypt it using their private encryption key, then verify the JWT's signature using Corppass' public keys, available at the Corppass JWKS endpoint.
  * **Access Token:** A signed JWS intended for the Corppass resource server(s). This sender-constrained token is required to query the UserInfo Endpoint for additional data.

### 4. Fetch Additional Data - Userinfo Endpoint

**Endpoint:** `/userinfo` | [View Specification](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/4.-userinfo-endpoint.md)

**Access:** Public TLS with Access Token and DPoP

If the application requires additional entity or user information - that is not present in the ID Token, query the UserInfo endpoint.

* **Action:** Send a `GET` request to the Userinfo endpoint, with the Access Token obtained from the Token Endpoint.
* **Result:** The response contains information based on the requested scopes, where applicable.
  * Authorization details for the authenticated user
  * Personal information for the authenticated user
  * Entity information for the transacting entity


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.