API docs by Redocly

SingPass Face Verification Service (1.0.0)

Download OpenAPI specification:Download

The SingPass Face Verification Service ("SingPass Face") verifies the facial features of a SingPass eligible user against the Governments' biometrics data source.

Release Notes

  • 1.0.0 (26 Jan 2021)
    • Official release
  • 1.1.0 (8 Mar 2023)
    • Addition of user API
    • Updated specifications for OAuth2.0 API

OAuth2.0 Access Token

OAuth2.0 API - Generates an access token for the SingPass Face Verification

Token is to be authenticated to access the Singpass Face Verification

Request Body schema: application/json
key
required
string

The key within the key-value pair of the header

value
required
string

The value within the key-value pair of the header

Responses

Request samples

Content type
application/json
{
  • "key": "Authorization",
  • "value": "Basic ZjU3M2ZiMjJiZDUxNDRmZTlhYjIzZjA5MTk0MDZjMzU6WkRZMVlUY3hOMkl0TW1JMU5TMDBPVGsxTFRrMU16SXRaak0yWWpnMU9HTmpOell5"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJvcmciOiIiLCJpZCI6IjFlZTNhZjllNWNkYjQ3NmFiMjI2OGE1ODBjMjE2OWZlIiwiaCI6InNoYTI1NiJ9",
  • "token_type": "bearer",
  • "expires_in": 1800
}

SingPass Face Verification

user API - Verifies if a user is eligible for SingPass Face Verification

Checks if a SingPass user is eligible for the face scan before generating a token.

Request Body schema: application/json
service_id
required
string

The service ID identifies the agency’s digital service.

user_id
required
string

The asserted identifier of the user. E.g. NRIC, FIN

transaction_type
string

Type of transaction (eg. onboarding, authentication)

Responses

Request samples

Content type
application/json
{
  • "service_id": "SingPass",
  • "user_id": "S1234567A",
  • "transaction_type": "SingPass onboarding"
}

Response samples

Content type
{
  • "registered": true
}

token API - Generates a session token based on the Face Verify method

Generate a session token for an SingPass user to initiate the face verification process based on the Face Verify method. This API would return a session token to be used when initialising the client SDK and calling the validate API.

Request Body schema: application/json
service_id
required
string

The service ID identifies the agency’s digital service.

user_id
required
string

The asserted identifier of the user. E.g. NRIC, FIN

transaction_type
string

Type of transaction (eg. onboarding, authentication)

Responses

Request samples

Content type
application/json
{
  • "service_id": "SingPass",
  • "user_id": "S1234567A",
  • "transaction_type": "SingPass onboarding"
}

Response samples

Content type
{
  • "token": "31706131726336496d655177346e55503279616b69547344446e5258684c7542"
}

validate API - Retrieves the face verification result based on the Face Verify method

This API would be called after the face scanning process to retrieve the face verification result. Subsequent calls will return a 400 error.

Request Body schema: application/json
service_id
required
string

The service ID identifies the agency's digital service.

user_id
required
string

The asserted identifier of the user (e.g. NRIC, FIN)

token
string

The token that is returned after calling the token API

ip
required
string

Public IP address of the device making this request

client
required
string

This is the information that describes the type of client device making the request (e.g. User Agent)

Responses

Request samples

Content type
application/json
{
  • "service_id": "SingPass",
  • "user_id": "S1234567A",
  • "token": "31706131726336496d655177346e55503279616b69547344446e5258684c7542",
  • "ip": "203.125.138.178",
  • "client": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36"
}

Response samples

Content type
{
  • "passed": true,
  • "token": "31706131726336496d655177346e55503279616b69547344446e5258684c7542",
  • "extra_data": {
    },
  • "reason": "Please Keep Still",
  • "retries_remaining": 5
}

SingPass Face Compare

Compare API - Compare a user's image based on the Face Compare method

This API will directly verify the user's captured photo based on the Face Compare method.

The image should be:

  • jpg or png
  • base64 encoded string
  • conform to international standard ISO/IEC 19794 Information technology - Biometric data interchange formats - Part 5: Face image data (supporting ICAO 9303 passports and ISO 18013 Driving Licences)
  • substantially in focus and un-obscured by flare or watermarks
  • having a minimum of 85 pixels between the eyes
  • under 2MB in size once encoded (encoding increases image size by approx 33%)
Request Body schema: application/json
service_id
required
string

The service ID identifies agency’s digital service.

user_id
required
string

The asserted identifier of the user. E.g. NRIC, FIN

transaction_type
string

Type of transaction (eg. onboarding, authentication)

image
required
string (Image)

base64 encoded png or jpg

Responses

Request samples

Content type
application/json
{
  • "service_id": "SingPass",
  • "user_id": "S1234567A",
  • "transaction_type": "SingPass onboarding",
  • "image": "string"
}

Response samples

Content type
{
  • "score": 0.90036
}