4. Parsing the ID Token
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.
The ID token returned during token exchange is a JSON Web Signature (JWS), which is also encrypted using JSON Web Encryption (JWE). The JWE and JWS components are represented using compact serialization form, as specified in section 3.1 of RFC 7516.
To reduce complexity, we recommend that you use a JWT parsing library to decrypt the token and to verify the signature, instead of implementing the decryption and signature verification yourself. You may refer to this list to look for a suitable JWT library for your programming language, though you must also ensure that your library of choice supports decryption of JWTs encrypted using JWE.
JWT Claims
The decrypted JWT will have the following claims:
sub
The principal that is the subject of the JWT. Contains a globally unique identifier for the user.
String
sub_account
This contains some information related to the user's identifiers. This is only returned if the sub_account
scope is requested.
Object containing key-value pairs. See the section below for full details.
act
An object describing actor acting on behalf of the sub
. This is currently unused, but this may be used in the future for delegation (e.g. a child acting on behalf of their parent, or vice-versa).
This object will contain a sub
claim, which contains the UUID of the actor. If the sub_account
scope is requested, it will also contain the sub_account
data for the actor.
If the sub_account
is returned, the format of sub_account
is described in the section below.
An object containing sub
and sub_account
(if requested).
aud
The client ID of your registered client, provided by Singpass during app onboarding.
A 32-character case-sensitive alphanumeric string.
iss
The issuer identifier of our authorization server.
String
iat
The unix timestamp, in seconds, at which we issued this JWT.
Number
exp
The unix timestamp, in seconds, on or after which this JWT must not be accepted for processing.
Number
amr
An array of authentication method references. This refers to the form factors used by the user to authenticate themselves.
The array will contain all the form factors used for this authentication. For example, if the user authenticated themselves using their password and SMS OTP, then this array will contain both pws
and otp-sms
.
Array of strings. The possible values are:
face
pwd
otp-sms
face-alt
swk
(software key)hwk
(hardware key)
Note that this list is non-exhaustive, and we reserve the right to introduce new values without prior notice to you.
nonce
This is the same nonce that you used in your authorization request.
String
The sub_account Claim
The sub_account
claim is an object that will always contain an account_type
property, which reflects the user's residency status or type of pass that they are holding. However, the other values returned in this object will contain different values depending on the user's account_type
, as explained below.
Singapore Citizen, Permanent Resident, or FIN holder
A user who is a Singapore Citizen, Permanent Resident, or FIN holder will have one of the following account_type
values:
SC/PR
Singapore Citizen or Permanent Resident
FIN
FIN holder
These users will have only one other property returned in the sub_account
claim, which is uinfin
.
uinfin
The user's NRIC number
9-character alphanumeric string.
Singpass Foreign Account Holders
A user who has a Singpass Foreign Account will have an account_type
of SFA
. The other properties returned in the sub_account
claim are as follows:
foreign_id
The user's foreign ID number
String
foreign_id_coi
The country of issuance of the user's foreign ID
2-letter country code.
Verification Checks
In order to ensure that the ID token is valid, you must perform the following checks:
Verify that the
iss
claim matches the issuer identifier of our authorization server, which you can obtain from theissuer
field in the OpenID configuration of our authorization server.Verify that the
aud
claim matches your client ID.Ensure that the current time is before the timestamp in the
exp
claim.Ensure that the
nonce
claim is the same as the nonce that you had sent in the authorization request.
If you are integrating with Singpass Login, then the flow ends here. If you are integrating with Myinfo (v5), then the next and final step would be to retrieve the user's information using the /userinfo
endpoint.
Last updated
Was this helpful?