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:
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/+_-=.]+
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.
invalid_request
The authentication request either had missing or invalid parameters. You should ensure that both client_id and request_uri were sent in the request, and that both are valid.
invalid_request_uri
The request_uri parameter provided was missing, malformed, expired, or was initiated from a different client. You should ensure that the request_uri being used is the one returned from the pushed authorization request, and that the client_id in the pushed authorization request is the same as the one that is included as a query parameter in the authorization request.
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:
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/+_-=.]+
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.
Once you have completed this check, you may proceed to perform token exchange to obtain the ID token and access token.
Last updated
Was this helpful?