2. Handling the Redirect

Note that the testing environment for the FAPI 2.0 Authentication API is not yet ready. It will be ready in December 2025. If you are integrating now, please refer to Singpass Authentication API instead.

Once the user has completed authentication on Singpass, we will redirect the user to the redirect_uri that you have specified in your authorization request.

Depending on whether the authentication was successful or not, the query parameters attached to the URL will be different.

Failed Authentication

If the user failed to authenticate, or if an error occurred, we may return an Authentication Error Response, as specified in section 3.1.2.6 of the OIDC specifications. The URL will contain the following query parameters:

Parameter	Description	Data type
error	An error code identifying the type of error that has occurred.	This will be an enum value. The possible values are detailed below.
error_description	A human-readable text description of the error.	String. This is optional.
error_uri	URI of a web page that includes additional information about the error	URL. This is optional.
state	This will be the same state parameter passed in the authorization request.	A string with a maximum length of 255 characters. It must match the regular expression pattern [A-Za-z0-9/+_-=.]+

Sample URL for Authentication Error Response

https://partner.gov.sg/redirect?error=invalid_request_uri&error_description=The%20request_uri%20provided%20is%20invalid&state=e32b9f28-5d34-4c0f-8b0e-6b670566c97f 

If you receive an Authentication Error Response, you should display an error page to your users. You may also display different content on your error pages depending on the error parameter. However, you should not display error or error_description verbatim on your web page in order to prevent content spoofing attacks.

Possible error values

The table below lists the possible values of the error query parameter that we may return.

error	What this error indicates
server_error	The server has encountered an unexpected error. You should guide the user to perform a retry.
temporarily_unavailable	The server is temporarily unavailable to handle the request. You should guide users to alternative authentication methods, or to guide them to try again some time later.

Successful Authentication

As per the OIDC specification, when the authentication is successful, the URL that the user is redirected to will contain two additional query parameters:

Parameter	Description	Data type
code	The authorization code. This will be used in a later step to obtain the user's ID token and access token.	A base64url-encoded string.
state	This will be the same state parameter passed in the authorization request.	A string with a maximum length of 255 characters. It must match the regular expression pattern [A-Za-z0-9/+_-=.]+

Sample URL for successful authentication

https://partner.gov.sg/redirect?code=XcyzlSeX1hIyJFlstxsSF_UeXC5DtiYkFgJ8VVx52mg&state=e32b9f28-5d34-4c0f-8b0e-6b670566c97f 

Upon redirect, your application's backend should check the state parameter provided and ensure that it is the same as the state which you have sent in the Pushed Authorization Request. This is an important measure to guard against CSRF attacks.

If you are using a certified OIDC Relying Party library, this check will be automatically performed by the library if you have configured it to do so.

Once you have completed this check, you may proceed to perform token exchange to obtain the ID token and access token.