# Migration Guide: Myinfo Business v1/v2 to v3 (FAPI 2.0)

This guide assists partners in transitioning existing integrations from Myinfo Business v2 (Legacy) to Myinfo Business v3.

Myinfo Business v3 is built on the [Corppass Authorization API (FAPI 2.0)](/technical-specifications/corppass-authorization-api-fapi-2.0.md), which adopts the Financial-grade API (FAPI) 2.0 Security Profile based 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 APIs. These changes align with global security best practices and provide long‑term reliability.

All legacy Myinfo Business v1/v2 applications will be deprecated, and partners must migrate to continue using the service.

***

## Key Changes

<table data-full-width="true"><thead><tr><th width="194.8046875">Feature</th><th>Myinfo Business (v1/v2)</th><th>Myinfo Business (v3) (FAPI 2.0)</th></tr></thead><tbody><tr><td><strong>API Endpoints</strong></td><td><p>Legacy API endpoints with base URL:</p><ul><li>Test: <code>https://test.api.myinfo.gov.sg/biz/[v1|v2]</code></li><li>Production: <code>https://api.myinfo.gov.sg/biz/[v1|v2]</code> </li></ul><p></p><p>Legacy endpoints:</p><ul><li>Authorization Endpoint (<code>/authorise</code>)</li><li>Token Endpoint (<code>/token</code>)</li><li>Entity-Person Endpoint (<code>/entity-person/{uen}/{uuid}</code>)</li></ul></td><td><p>Different set of API endpoints with base URL:</p><ul><li>Staging: <code>https://stg-id.corppass.gov.sg</code></li><li>Production: <code>https://id.corppass.gov.sg</code> </li></ul><p></p><p>Standard OIDC / FAPI 2.0 endpoints:</p><ul><li>Well-known Endpoints (<code>/.well-known/openid-configuration</code>) - where the following endpoints are dynamically obtained</li><li>Pushed Authorization Request Endpoint</li><li>Authorization Endpoint</li><li>Token Endpoint</li><li>Userinfo Endpoint</li></ul><p></p><p>Refer to <a href="/pages/iJYjfxlGnnX8R9ei7eQc">Integration Guide</a> for more details.</p></td></tr><tr><td><strong>Enhanced Security</strong></td><td>Standard authorization code flow</td><td><p>Enhanced security with</p><ul><li><strong>Mandatory</strong> <a href="/pages/LywRxjs8azw2UCtFr8yf"><strong>Client Assertion</strong></a> requirements.</li><li><strong>Mandatory</strong> <a href="/pages/TOFgMaQYGoeEs2HmOyj3"><strong>Proof Key of Code Exchange (PKCE)</strong></a>.</li><li><strong>Mandatory</strong> <a href="/pages/QOVgmxTpNTkdnLGQCrH6"><strong>Demonstrating Proof of Possession (DPoP)</strong></a> (sender-constrained tokens).</li></ul></td></tr><tr><td><strong>Authorization Flow</strong></td><td>Authorization parameters provided via <em>front-channel</em> (params in URL).</td><td><p>Authorization parameters provided via <em>back-channel</em> <strong>Pushed Authorization Request (PAR)</strong> endpoint.</p><p></p><p>Refer to <a href="/pages/Ah0kPLGW3E6t1tnusPN6">Pushed Authorization Request</a> for more details.</p></td></tr><tr><td><strong>Authorization Request Parameters</strong></td><td><p>Authorization Endpoint:</p><ul><li><code>client_id</code></li><li><strong><code>authmode</code></strong></li><li><strong><code>purpose</code></strong></li><li><code>response_type</code></li><li><code>redirect_uri</code></li><li><strong><code>attributes</code></strong></li><li><code>state</code></li></ul></td><td><p>Pushed Authorization Request:</p><ul><li><code>client_id</code></li><li><strong><code>client_assertion</code></strong></li><li><strong><code>client_assertion_type</code></strong></li><li><strong><code>code_challenge</code></strong></li><li><strong><code>code_challenge_method</code></strong></li><li><code>response_type</code></li><li><code>redirect_uri</code></li><li><strong><code>scope</code></strong></li><li><code>state</code></li><li><strong><code>nonce</code></strong></li><li><strong><code>acr_values</code></strong></li><li><strong><code>dpop_jkt</code></strong></li></ul><p></p><p>Authorization Endpoint:</p><ul><li><code>client_id</code></li><li><strong><code>request_uri</code></strong> </li></ul><p></p><p>Refer to <a href="/pages/Ah0kPLGW3E6t1tnusPN6">Pushed Authorization Request</a> and <a href="/pages/be3ILFlYmJIRS9Hv9uv3">Authorization Endpoint</a> for more details.</p></td></tr><tr><td><strong>Token Request Parameters</strong></td><td><p>Token Endpoint:</p><ul><li><code>code</code></li><li><code>redirect_uri</code></li><li><code>grant_type</code></li><li><code>client_id</code></li><li><strong><code>client_secret</code></strong></li><li><strong><code>state</code></strong></li></ul></td><td><p>Token Endpoint:</p><ul><li><code>code</code></li><li><code>redirect_uri</code></li><li><code>grant_type</code></li><li><code>client_id</code></li><li><strong><code>client_assertion_type</code></strong></li><li><strong><code>client_assertion</code></strong></li><li><strong><code>code_verifier</code></strong> </li></ul><p></p><p>Refer to <a href="/pages/tdw1eZJeFJxNFBu1QGx2">Token Endpoint</a> for more details.</p></td></tr><tr><td><strong>Data Retrieval Endpoint</strong></td><td><p>Endpoint: <code>/entity-person/{uen}/{uuid}</code></p><p></p><p><code>uen</code> and <code>uuid</code> are obtained from the <code>sub</code> (uen_uuid) value in the decoded access_token.</p><p></p><p>Legacy payload structure within:</p><ul><li><code>entity</code></li><li><code>person</code></li></ul></td><td><p><strong>Endpoint: <code>/userinfo</code></strong> (Standard OIDC endpoint)</p><p></p><p>No longer required to provide <code>uen</code> and <code>uuid</code> values as these are handled through the Standard OIDC flow. Access Token is to be treated as opaque string.</p><p></p><p><strong>Updated payload structure</strong> within:</p><ul><li><code>entity_info</code></li><li><code>person_info</code></li><li><code>corppass_info</code></li></ul><p></p><p>Refer to <a href="/pages/fFIrslCA8R1d2tn8SIza">Userinfo Endpoint</a> for more details.</p></td></tr><tr><td><strong>Error Handling</strong></td><td><p>Legacy / custom error formats.</p><ul><li><p>API response</p><ul><li><code>code</code></li><li><code>message</code> </li></ul></li><li><p>Redirect URI</p><ul><li><code>error</code></li><li><code>error_description</code></li><li><code>state</code></li></ul></li></ul></td><td><p><strong>Standardised OAuth 2.0 Errors</strong>.</p><ul><li><code>error</code></li><li><code>error_description</code></li><li><code>state</code></li></ul></td></tr><tr><td><strong>Scopes</strong></td><td>Category-based entity scopes and fine-grained person scopes (<code>basic-profile</code>, <code>financials</code>, <code>capitals</code>, <code>name</code>, <code>uinfin</code>)</td><td><p><strong>Fine-grained scopes</strong> across entity and person scopes (e.g., <code>entity.basic_profile.name</code>, <code>entity.basic_profile.uen_status</code>, <code>user.name</code>), allowing for more precise data access control.</p><p></p><p>Refer to <a href="/pages/q3CXMPDqHJH1lIWjMOBl">Myinfo Business Scopes</a> for more details.</p></td></tr></tbody></table>

***

## Migration Steps

### Step 1: Create Myinfo Business v3 Application

Create a new Myinfo Business v3 application on the [Singpass Developer Portal (SDP)](https://developer.singpass.gov.sg/). Existing Client ID / App ID cannot be used in the new version as they are not interchangeable.

Refer to [Getting Started](/products/myinfo-business/getting-started.md) guide for step-by-step instructions on creating and configuring your application.

### Step 2: Implement Myinfo Business v3 Integration

Myinfo Business v3 is built on the [Corppass Authorization API (FAPI 2.0)](/technical-specifications/corppass-authorization-api-fapi-2.0.md) and introduces significant changes to the authorization flow, security requirements, and data handling.

As the APIs and integration patterns differ substantially from v1/v2, partners are required to implement the integration based on the latest specifications.

Refer to [Integration Guide](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide.md) for full implementation details.


---

# 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/migration-guides/migration-guide-myinfo-business-v1-v2-to-v3-fapi-2.0.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.