This API triggers SingPass login and obtain consent for the user to retrieve user's data from MyInfo.
Once the user has authenticated and consented, an authorisation code (authcode) will be returned together with the state for verification via the callback URL defined.
The authcode can then be used to retrieve an access token via the Token API.
Note: This API is public and should be implemented as a link or button on your online webpage.
Note: For partners integrating via android mobile application, please ensure that the "setDomStorageEnable" attribute is enabled.
Query parameters
authmodestring · enumOptional
Mode of authentication used to obtain user consent. Default is "SINGPASS".
Default: SINGPASSPossible values:
purposestringRequired
State the purpose for requesting the data. This will be shown to the user for his consent.
response_typestringOptional
Response type for authorisation code flow - must be "code".
Default: code
attributesstring[]Required
Comma separated list of attributes requested. Possible attributes are listed in the scopes of the OAuth2 Security Schema above.
Example: name,hanyupinyinname
statestringRequired
Identifier that represents the user's session/transaction with the client for reconciling query and response. The same value will be sent back via the callback URL. Use a unique system generated number for each user/transaction.
redirect_uristringRequired
Your callback URL for MyInfo to return with the authorisation code.
client_idstringRequired
Unique ID for your application.
Example: STG-180099999K-TEST01
login_typestring · enumOptional
Pilot for SingPass-QR-only-login using SingPass Mobile. SingPass-QR-only-login is enabled by specifying this parameter with value set to QR.
Note that this only applies to digital service on-boarded to perform SingPass-QR-only-login.
Default: SINGPASSPossible values:
appLaunchURLstringOptional
Url scheme to launch back your mobile app after successful authentication using SingPass mobile.
Responses
302
Service will redirect all responses to 'redirect_uri' with additional parameters added as response results. Expected parameters include:
- **code**: this is the authorisation code you will use when calling the token endpoint
- **state**: this should be the same state passed in your initial URL.
- **error**: if there are any errors encountered, the error code will be given in this parameter.
- **'500'** - Unknown or other server side errors.
- **'503'** - MyInfo under maintenance. Error description will also be given in error_description parameter.
- **'access_denied'** - When user did not give consent, refer to error_description parameter for the reason.
- **error_description**: if error is 'access_denied' i.e. user did not give consent, the description will be 'Resource Owner did not authorize the request'.
**Note:** If user closes the browser window prematurely, there will be no callback to the 'redirect_uri'. Therefore it is important for you to check the 'state' to verify that the transaction is the same.
302
Service will redirect all responses to 'redirect_uri' with additional parameters added as response results. Expected parameters include:
code: this is the authorisation code you will use when calling the token endpoint
state: this should be the same state passed in your initial URL.
error: if there are any errors encountered, the error code will be given in this parameter.
'500' - Unknown or other server side errors.
'503' - MyInfo under maintenance. Error description will also be given in error_description parameter.
'access_denied' - When user did not give consent, refer to error_description parameter for the reason.
error_description: if error is 'access_denied' i.e. user did not give consent, the description will be 'Resource Owner did not authorize the request'.
Note: If user closes the browser window prematurely, there will be no callback to the 'redirect_uri'. Therefore it is important for you to check the 'state' to verify that the transaction is the same.
No content
Token
post
This API generates an access token when presented with a valid authcode obtained from the Authorise API. This token can then be used to request for the user's data that were consented.
Note: This header is not required when calling Sandbox API.
Body
codestringRequired
The authcode given by the authorise API.
grant_typestringOptional
Grant type for getting token (default "authorization_code")
Default: authorization_code
client_secretstringRequired
Secret key given to your application during onboarding.
client_idstringRequired
Unique ID for your application.
redirect_uristringRequired
Application's callback URL.
statestringOptional
Identifier that represents the user's session with the client, provided earlier during the authorise API call.
Responses
200
OK.
Returning a JSON object which contains the authorization access token (JWT) that will be used to retrieve the data from MyInfo.
application/json
400
Possible scenarios:
- Same authcode in the body is being re-used.
We do not allow same authcode being used in multiple calls. Ensure that authcode is not repeated.
- AuthCode error - missing, invalid, expired, revoked
application/json
401
Unauthorized.
Possible scenarios:
- No security header given (HTTP 'Authorization' header)
- Invalid App ID used. Digital service is not registered with MyInfo
- Invalid client secret used.
- The timestamp of server is not synchronised. Check timestamp of server.
- The value of the nonce in the authorisation header was deemed to be repeated. Check that the nonce is not re-used
- Ensure HTTP 'Authorization' header to be 'PKI_SIGN'
- Signature incorrect - Verify your signature by using our signature verifier tool and ensure correct key is used to sign the base string.
- Ensure that base string contains all parameters required
- Ensure attributes in base string are separate by comma(,), and not %2C
- Ensure that correct key is used to sign the base string
- Ensure that HTTP call is made with the same query/body parameters used to formulate the base string.
- Ensure the base string contains the following:
1. HTTP GET method(in uppercase)
2. API (e.g. https://..)
3. These parameters:
* app_id
* nonce
* signature
* signature_method
* timestamp
application/json
403
Forbidden
Possible scenarios:
- Incorrect API URL used. Refer to tutorial for the correct API URL(test/production)
application/json
500
Unexpected error. Check response body for actual error.
This API returns user's data from MyInfo when presented with a valid access token obtained from the Token API.
Note: Null value indicates that an attribute is unavailable.
Authorizations
Path parameters
substringRequired
Identifier of user obtained from 'sub' attribute in access token. May be UINFIN or UUID.
Example: 9E9B2260-47B8-455B-89B5-C48F4DB98322
Query parameters
txnNostringOptional
Transaction ID from requesting digital services for cross referencing.
attributesstring[]Required
Comma separated list of attributes requested. Possible attributes are listed in the scopes of the OAuth2 Security Schema above.
Example: name,hanyupinyinname
client_idstringRequired
Unique ID for your application.
Example: STG-180099999K-TEST01
subentitystringOptional
UEN of SaaS partner's client that will be receiving the person data.
Example: 180099736H
Header parameters
AuthorizationanyRequired
Add authorization token constructed containing the RSA digital signature of the base string. Refer to https://api.singpass.gov.sg/library/myinfo/developers/tutorial3 on how this token should be generated. Also include the access token (JWT) from /token API in your header prefixed with 'Bearer'.
Note: Only the Bearer token is required when calling Sandbox API.
Responses
200
OK.
**Note:**
- Response Content-Type will be 'application/jose', which is a JSON object conforming to the JWE standard (https://tools.ietf.org/html/rfc7516).
- Response contents are first signed, then encrypted. In order to access the data, your application should do the following steps in order:
1. Decrypt the payload with your application's private key.
2. Validate the decrypted payload signature with our public key.
- After doing the above steps, your application will be able to extract the payload in JSON format.
application/json
Responseall of
Person instance's details
and
and
401
Unauthorized.
Possible scenarios:
- No security header given (HTTP 'Authorization' header)
- Invalid App ID used. Digital service is not registered with MyInfo
- The timestamp of server is not synchronised. Check timestamp of server.
- The value of the nonce in the authorisation header was deemed to be repeated. Check that the nonce is not re-used
- Ensure HTTP 'Authorization' header to be 'PKI_SIGN'
- Signature incorrect - Verify your signature by using our signature verifier tool and ensure correct key is used to sign the base string.
- Ensure that base string contains all parameters required
- Ensure attributes in base string are separate by comma(,), and not %2C
- Ensure that correct key is used to sign the base string
- Ensure that HTTP call is made with the same query/body parameters used to formulate the base string.
- Ensure the base string contains the following:
1. HTTP GET method(in uppercase)
2. API (e.g. https://..)
3. These parameters:
* app_id
* nonce
* signature
* signature_method
* timestamp
- The requested 'sub' does not match the identifier of the person who logged in
- Requested attributes do not match the attributes consented by person.
This happens if the list of attributes in your request are different from the attributes specified when calling the token API.
Details will be given in the error object returned.
application/json
403
Forbidden
Possible scenarios:
- Incorrect API URL used. Refer to tutorial for the correct API URL(test/production)
- Request contains attributes not allowable for the digital service.
application/json
404
Not Found.
Possible scenarios.
- Missing MyInfo profile due to UIN/FIN accessing his MyInfo account less than a day after SingPass account activation.
application/json
500
Unexpected error. Check response body for actual error.
