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.
get
/com/v3/authorise
JavaScript
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
/com/v3/token
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.
Authorizations
HTTPRequired
PKI digital signature for server to server calls. See Request Signing for more details.
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.
application/json
post
/com/v3/token
NodeJS
Person
get
/com/v3/person/{sub}/
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
OAuth2authorizationCodeRequired
The following are the available OAuth2 scopes for MyInfo APIs
Authorization URL: Token URL:
HTTPRequired
PKI digital signature for server to server calls. See Request Signing for more details.
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:
Decrypt the payload with your application's private key.
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
Person instance's details
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.
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.
// function to prepare request for TOKEN API
function createTokenRequest(code) {
var cacheCtl = "no-cache";
var contentType = "application/x-www-form-urlencoded";
var method = "POST";
var request = null;
// preparing the request with header and parameters
// assemble params for Token API
var strParams = "grant_type=authorization_code" +
"&code=" + code +
"&redirect_uri=" + _redirectUrl +
"&client_id=" + _clientId +
"&client_secret=" + _clientSecret;
var params = querystring.parse(strParams);
// assemble headers for Token API
var strHeaders = "Content-Type=" + contentType + "&Cache-Control=" + cacheCtl;
var headers = querystring.parse(strHeaders);
// Sign request and add Authorization Headers
var authHeaders = generateAuthorizationHeader(
_tokenApiUrl,
params,
method,
contentType,
_authLevel,
_clientId,
_privateKeyContent,
_clientSecret
);
if (!_.isEmpty(authHeaders)) {
_.set(headers, "Authorization", authHeaders);
}
var request = restClient.post(_tokenApiUrl);
// Set headers
if (!_.isUndefined(headers) && !_.isEmpty(headers))
request.set(headers);
// Set Params
if (!_.isUndefined(params) && !_.isEmpty(params))
request.send(params);
return request;
}
// function to prepare request for PERSON API
function createPersonRequest(sub, validToken) {
var url = _personApiUrl + "/" + sub + "/";
var cacheCtl = "no-cache";
var method = "GET";
var request = null;
// assemble params for Person API
var strParams = "client_id=" + _clientId +
"&attributes=" + _attributes;
var params = querystring.parse(strParams);
// assemble headers for Person API
var strHeaders = "Cache-Control=" + cacheCtl;
var headers = querystring.parse(strHeaders);
var authHeaders;
// Sign request and add Authorization Headers
authHeaders = generateAuthorizationHeader(
url,
params,
method,
"", // no content type needed for GET
_authLevel,
_clientId,
_privateKeyContent,
_clientSecret
);
if (!_.isEmpty(authHeaders)) {
_.set(headers, "Authorization", authHeaders + ",Bearer " + validToken);
}
else {
// NOTE: include access token in Authorization header as "Bearer " (with space behind)
_.set(headers, "Authorization", "Bearer " + validToken);
}
// invoke person API
var request = restClient.get(url);
// Set headers
if (!_.isUndefined(headers) && !_.isEmpty(headers))
request.set(headers);
// Set Params
if (!_.isUndefined(params) && !_.isEmpty(params))
request.query(params);
return request;
}
