Migration Guide: Legacy to FAPI 2.0

This guide assists partners in transitioning existing integrations from the Corppass Authorization API (Legacy) to the new FAPI 2.0‑compliant Authorization API.

The new implementation strengthens security by adopting the Financial-grade API (FAPI) 2.0 Security Profile, built on OAuth 2.0 and OpenID Connect.

Why Migrate?

FAPI 2.0 introduces enhanced security mechanisms, mandated flows, and updated token structures that improve confidentiality, integrity, and replay protection compared to the Legacy Security Profile. These changes align with global security best practices and provide long‑term reliability.

Legacy Security Profile will be deprecated, and partners must migrate to continue using the service.

---

Key Changes

See Changelog: FAPI 2.0 Launch

Feature	Legacy Security Profile	FAPI 2.0 Security Profile
Enhanced Security	Standard authorization code flow	Enhanced security with Stricter TTL requirements. Stricter Client Assertion requirements. Mandatory Proof Key of Code Exchange (PKCE). Mandatory Demonstrating Proof of Possession (DPoP) (sender-constrained tokens). Stricter set of allowed TLS cipher suites. Enforce HTTPS scheme for callback redirect URLs
Authorization Flow	Authorization parameters provided via front-channel (params in URL).	Authorization parameters provided via back-channel Pushed Authorization Request (PAR) endpoint. The requests are also contextualised with new parameters for Corppass Login applications: authentication_context_type authentication_context_message Refer to Pushed Authorization Request for more details.
Authorization Request Parameters	Authorization Endpoint: client_id code_challenge code_challenge_method response_type redirect_uri scope state nonce	Pushed Authorization Request: client_id client_assertion client_assertion_type code_challenge code_challenge_method response_type redirect_uri scope state nonce acr_values dpop_jkt Authorization Endpoint: client_id request_uri Refer to Pushed Authorization Request and Authorization Endpoint for more details.
ID Token	Flat, custom structure. sub encapsulating user information. entityInfo encapsulating entity information. userInfo encapsulating acting user's information.	Structured, hierarchical structure. sub representing subject (entity / user) identifier. sub_attributes encapsulating profile information about the subject (entity on primary / root level, user on actor level). act encapsulating information about the subject acting on behalf of the primary subject. Refer to ID Token section for more details.
Userinfo Endpoint (Additional User / Authorization Data Retrieval)	Endpoint: /authorization-info. Returns PascalCase keys: AuthInfo TPAuthInfo Format: JWS	Endpoint: /userinfo (Standard OIDC endpoint name) Returns snake_case keys: auth_info tp_auth_info Format: JWE Refer to Userinfo Endpoint for more details.
Error Handling	Legacy / custom error formats.	Standardised OAuth 2.0 Errors. error error_description state
Scopes	Standard scopes (openid, authinfo, tpauthinfo)	Finer-grained scopes (e.g., entity.identity, user.identity, user.name), allowing for more precise data access control. Refer to Scopes section for more details.

---

Migration Steps

Step 1: Review Client Configuration & Scopes

Review your client configuration on the Corppass Developer Portal to accommodate new mandatory parameters and scope changes.

1. Review Authentication Context Type: FAPI 2.0 introduces authentication_context_type as a mandatory parameter to define the transaction context.

   1. Configuration: Your client profile now includes a list of "Supported Authentication Context Types". Currently, only APP_AUTHENTICATION_DEFAULT is supported. This value will be automatically backfilled for all existing clients.

   2. Constraint: During an authorization request, you can only request a context type that is explicitly configured for your client. For now, you must use APP_AUTHENTICATION_DEFAULT value in your requests.

   Refer to Authentication Context Parameters section for more details.

2. Review Scopes: FAPI 2.0 introduces new finer-grained scopes.

   1. Configuration: To ensure continuity, Corppass will automatically backfill your client profile with finer-grained FAPI 2.0 scopes corresponding to your legacy access.

   2. Review: Audit the backfilled scopes in your client configuration. Remove any that provides access to data your application no longer needs.

   Refer to Scopes section for more details.

1. Review OIDC Redirect URLs: FAPI 2.0 now mandates the use of redirect URLs with https scheme.

   1. Configuration: Make sure you have at least one usable redirect URL with https scheme configured.

   2. Constraint: During an authorization request, you must provide a redirect URL with https scheme, or else you will not be allowed to initialise authorization on FAPI 2.0.

Step 2: Retrieve new metadata from OpenID discovery endpoint

The OpenID Connect Discovery URL remains the same as the Legacy API.

1. New Endpoints Metadata: Query the existing Discovery URL to retrieve updated provider metadata. Configure your application to use the new endpoint values found in the metadata:

   1. pushed_authorization_request_endpoint (New: Required for PAR)

   2. userinfo_endpoint (Replaces /authorization-info)

Refer to OpenID Discovery Endpoint for more details.

Step 3: Authorization Request

Significant Change: You can no longer construct the authorization URL directly in the browser. You need to implement Pushed Authorization Request (PAR).

1. Call the PAR Endpoint (/request):

   1. Initiate the flow via a back-channel POST request.

   2. Include DPoP proof in the request.

   3. Include the necessary OIDC parameters (e.g., client_id, scope, redirect_uri) along with the new mandatory fields (e.g., client_assertion, code_challenge, authentication_context_type).

   4. Corppass returns a request_uri that references your payload.

2. Browser Redirect to Authorization Endpoint (/authorize):

   1. Redirect the user to the Authorization Endpoint using only client_id and the returned request_uri returned in the previous step.

   2. This replaces the Legacy method of exposing sensitive parameters directly in the browser URL.

Refer to Pushed Authorization Request (PAR) Endpoint for more details.

Step 4: Token Exchange

The Token Endpoint (/token) now enforces strict security proofs.

1. Prepare the Request:

   1. Mandatory Client Authentication: Use client_assertion (Private Key JWT).

   2. Mandatory PKCE: Include the code_verifier matching the code_challenge from PAR.

   3. Mandatory DPoP: Include a DPoP HTTP header. The public key in this header will be bound to the resulting Access Token.

2. Handle the Response:

   1. Access Token: Store the opaque token for subsequent API calls where needed.

      1. Note: The token is sender-constrained; you must use the same DPoP private key from the request to sign the DPoP header when using this token later.

   2. ID Token: Decrypt the JWE using your private encryption key to retrieve the signed payload, then validate the signature. See Step 5.

Refer to Token Endpoint for more details.

Step 5: Decrypt & Map ID Token

The ID Token is an Encrypted JWT (JWE).

1. Decrypt: Use your private encryption key (from Step 2) to decrypt the token.

2. Validate: Verify the signature of the decrypted payload using Corppass's public signing key.

3. Map New Claims: Update your parsing logic to the new hierarchical structure.

Data	Legacy Claim	FAPI 2.0 Claim
Entity Details	entityInfo.* { "entityInfo": { "CPEntID": "T09LL0001B", "CPEnt_TYPE": "UEN", "CPEnt_Status": "Registered", "CPNonUEN_Country": "", "CPNonUEN_RegNo": "", "CPNonUEN_Name": "" } }	sub, sub_attributes.* { "sub": "T09LL0001B", "sub_type": "entity", "sub_attributes": { "entity_type": "UEN", "entity_reg_number": "T09LL0001B", "entity_coi": "SG", "entity_name": "My Example Company", "entity_uen_status": "Registered" } }
User Details	sub { "sub": "s=S1234567P,uuid=0f14a2fc-09c2-4780-95f0-8c28347f2780,u=CP192,c=SG" } userInfo.* { "userInfo":{ "CPAccType": "User", "CPUID_FullName": "John Grisham", "ISSPHOLDER": "YES" } }	act.* { "act": { "sub": "0f14a2fc-09c2-4780-95f0-8c28347f2780", "sub_type": "user", "sub_attributes": { "account_type": "standard", "identity_number": "S1234567P", "identity_coi": "SG", "name": "John Grisham" } } }

Refer to ID Token section for more details.

Step 6: Userinfo Endpoint

This is applicable if your application fetches additional user / authorization data.

1. Use the new userinfo URL

   1. In the legacy API, this was available on the /authorization-info endpoint.

   2. In the FAPI 2.0 API, this is served on the /userinfo endpoint (the metadata retrieved in Step 2, under userinfo_endpoint).

2. Update Authorization header prefix to be DPoP instead of Bearer

   1. In the legacy API, the Authorization header would have been sent as a bearer token:

      Authorization: Bearer <your_access_token>

   2. In the FAPI 2.0 API, this needs to be sent with a DPoP prefix:

      Authorization: DPoP <your_access_token>

3. Handle new response format

   1. Update your JSON parser to handle snake_case keys (e.g., auth_info instead of AuthInfo).

   2. Since the response is now returned as a JWE, you must decrypt the payload using your registered private key before processing the claims.

Refer to Userinfo Endpoint for more details.

Step 7: Error Handling

Ensure your application handles standard OAuth 2.0 error parameters (error, error_description, state):

1. Handle Redirect URI: Error query parameters on the callback URL (e.g., https://client.com/cb?error=access_denied&error_description=...)

2. Handle API Response: JSON bodies for /request, /token , or userinfo failures.

Refer to the respective endpoints for more details.