Retrieves a sample Person data from Myinfo based on UIN/FIN.
This API does not use OAuth2.0 to perform authentication or authorisation, and does not require authorisation token and digital signature.
Note: Null value indicates that an attribute is unavailable.
Path parameters
uinfinstringRequiredExample: S9812381D
Query parameters
scopestring[]Optional
Space separated list of scope requested. Possible scopes are listed in the scopes of the OAuth2 Security Schema above.
Example: name hanyupinyinname
Responses
200
OK.
Note:
Response will be a JSON object.
application/json
Person instance's details
get
/com/v4/person-sample/{uinfin}/
Shell
200
OK.
Note:
Response will be a JSON object.
Authorise
get
/com/v4/authorize
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 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 partner's online webpage.
Note: For partners integrating via android mobile application, please ensure that the "setDomStorageEnable" attribute is enabled.
Query parameters
purpose_idstringRequired
purpose_id should have a corresponding pre-registered purpose(s) description as part of the setup. Purpose description refers to what the user will see in the consent page
response_typestringRequired
Response type for authorisation code flow - must be "code".
Default: code
scopestring[]Required
Space separated list of scopes requested. Possible scopes are listed in the scopes of the OAuth2 Security Schema above.
Example: name hanyupinyinname
code_challengestringRequired
Value resulting from performing Base64 encoding of a SHA256 hash of code_verifier (cryptographic random value generate on server side.) Refer to the section on Proof Key for Code Exchange (PKCE) for more information.
Hashing method used in producing code_challenge. Only supports 'S256'
Example: S256
redirect_uristringRequired
Partner's callback URL for Myinfo to return with the authorisation code.
client_idstringRequired
Unique ID for partner's application.
Example: STG-180099999K-TEST01
app_launch_urlstringOptional
Url scheme to launch back user's mobile app after successful authentication using Singpass mobile.
subentity_idstringOptional
UEN of the SaaS partner's client that will be receiving the person data.
Example: 180099736H
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 partner will use when calling the token endpoint
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.
'invalid_scope' - When application requests for scope(s) that is not permitted.
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'.
if error is 'invalid_scope' i.e. scope requested is not allowed, the description will be either 'Invalid realm scope' or 'Invalid client scope'.
Note: If user closes the browser window prematurely, there will be no callback to the 'redirect_uri'.
get
/com/v4/authorize
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 partner will use when calling the token endpoint
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.
'invalid_scope' - When application requests for scope(s) that is not permitted.
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'.
if error is 'invalid_scope' i.e. scope requested is not allowed, the description will be either 'Invalid realm scope' or 'Invalid client scope'.
Note: If user closes the browser window prematurely, there will be no callback to the 'redirect_uri'.
No content
Token
post
/com/v4/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
clientassertion
PKI digital signature of assertion metadata for client authentication. Signature will be verified using the public signing key listed in Relying Party's JWKS.
PKCE
OAuth security extention to prevent CSRF and authorization code injection attacks. This replaces the 'state' parameter.
Header parameters
DPoPstringRequired
DPoP Proof (JWT) containing the partner's ephemeral public signing key that can be used to prove legit possession of the access token issued.
Body
codestringRequired
The authcode given by the authorise API.
grant_typestringRequired
Grant type for getting token (default "authorization_code")
Default: authorization_code
client_idstringRequired
Unique ID for your application.
redirect_uristringRequired
Application's callback URL.
client_assertionstringRequired
The assertion being used to authenticate the client. Refer to the Security section on Client Assertion for more details.
client_assertion_typestringRequired
The format of the assertion, which is defined to be 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
// function to prepare request for PERSON API
callPersonAPI = async function (uuid, accessToken, sessionEphemeralKeyPair) {
let urlLink;
urlLink = CONFIG.PERSON_URL + '/' + uuid;
let cacheCtl = 'no-cache';
let method = constant.HTTP_METHOD.GET;
// assemble params for Person API
let strParams = 'scope=' + encodeURIComponent(CONFIG.SCOPE);
// assemble headers for Person API
let strHeaders = 'Cache-Control=' + cacheCtl;
let headers = querystring.parse(strHeaders);
//generate ath to append into DPoP
let ath = this.securityHelper.base64URLEncode(this.securityHelper.sha256(accessToken));
//generate DPoP
let dpopToken = await this.securityHelper.generateDpop(urlLink, ath, method, sessionEphemeralKeyPair);
headers['dpop'] = dpopToken;
headers['Authorization'] = 'DPoP ' + accessToken;
// invoke entity person API
let personURL = CONFIG.PERSON_URL;
let parsedUrl = urlParser.parse(personURL);
let domain = parsedUrl.hostname;
let requestPath = parsedUrl.path + '/' + uuid + '?' + strParams;
//invoking https to do GET call
let personData = await requestHandler.getHttpsResponse(method, 'https://' + domain + requestPath, headers, null, null);
return personData.data;
};
