/authenticateUser/v2

Description

This service validates both liveness and facial authentication. It compares the biometric template (templateRaw), which was previously validated and stored in the client's data repository during the Onboarding process, with a bestImageToken generated at the time of authentication.

Functionality

1. First Call: Establishes a unique userId for the user.
2. Authentication: In each authentication attempt, the userId is sent along with the registered biometric template. This template is compared with the current tokenized image (bestImageToken). If there is a match and the liveness check is passed, the user is successfully authenticated.

Request:

curl --location '{IDENTITY_API_BASE_URL}/services/authenticateUser/v2' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "userId": "001",
    "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF…",
    "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT…",
    "merchantReferenceId": "authenticate-001",
    "tracking": {
        "extraData": "BQABAQG2gBNjuHN...",
        "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
    }
}'

Request parameters:

Parameter	Type (Content)	Required	Description
userId	String	Yes	Unique identifier for the user. Must be persisted and associated with the corresponding biometric template. Needs to be at least two digits.
registeredTemplateRaw	String (Base64)	Yes	Template generated by the Selphi widget, AES256 encrypted and tokenized, sent in Base64 format. Represents the user's facial pattern with the most frontal face pose detected.
image	String (Base64)	No	[Optional] Base64 formatted image obtained from the civil registry. Becomes mandatory if the registered biometric template ("registeredTemplateRaw") is not provided.
bestImageToken	String (Base64)	Yes	Tokenized bestImage property generated by the Selphi widget at the time of authentication.
template	String (Base64)	No	[Optional] Base64 formatted biometric template. Becomes mandatory if tokenized bestImage ("bestImageToken") is not provided.
merchantReferenceId	String	Yes	Client reference for each authentication. It is recommended that this data does not contain sensitive information such as PII (personally identifiable information).
tracking	JSON Object	No	Object that represents necessary tracking information.
extraData	String (Base64)	No	Token generated by Mobile/Web SDK. Contains tokenized tracking information.
operationId	String (Base64)	No	Operation identifier generated by Mobile/Web SDK.

Example Body with registeredTemplateRaw:

{
    "userId": "001",
    "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF…",
    "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT…",
    "merchantReferenceId": "authenticate-001",
    "tracking": {
        "extraData": "BQABAQG2gBNjuHN...",
        "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
    }
}

Example Body with image:

{
    "userId": "001",
    "image": "/9j/4AAQ...",
    "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT…",
    "merchantReferenceId": "authenticate-001",
    "tracking": {
        "extraData": "BQABAQG2gBNjuHN...",
        "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
    }
}

Response fields:

Identifier	Type	Description
timestamp	String	Timestamp (UTC) of the response in the format: YYYY-MM-DDThh:mm:ss.SSSZ
transactionId	String	Transaction identifier associated with the request processed by the API.
serviceResultCode	Integer	Code indicating the overall result of the service execution. See Table 1 - Service Result Code
serviceResultLog	String	Descriptive field of the execution result when there is an error or exception. If successful, it indicates the result code description.
serviceFacialSimilarityResult	Float	Value indicating the facial similarity between the registeredTemplateRaw and the bestImageToken. 1.0 = 100%.
serviceFacialAuthenticationLog	String	Descriptive field of the facial authentication execution result. Includes details when there is an error or exception in the module.
serviceFacialAuthenticationResult	Integer	Code indicating the result of the facial authentication. See Table 2 - Service Facial Authentication Result
serviceLivenessResult	Integer	Code indicating the result of the passive liveness test evaluation. See Table 3 - Service Liveness Result
serviceLivenessLog	String	Descriptive field of the passive liveness execution result. Includes details when there is an error or exception.
merchantReferenceId	String	Reference sent in the body of the request.
registeredTemplateRaw	String	[Optional] Registered biometric template returned by the SelphID SDK extract for use in subsequent authentications.

Example Response:

{
    "merchantReferenceId": "82b0084f-ddec-4415-8d2f-b085b42a0155",
    "serviceResultCode": 0,
    "serviceResultLog": "",
    "serviceFacialSimilarityResult": 0.9946970343589783,
    "serviceFacialAuthenticationLog": "Positive",
    "serviceFacialAuthenticationResult": 3,
    "serviceLivenessLog": "Live",
    "serviceLivenessResult": 3,
    "timestamp": "2024-10-29T20:29:24Z",
    "transactionId": "531ecbb1-de3d-4907-a737-0db236674e9a",
    "registeredTemplateRaw": "BAIBAQGo+puJyHjfRD8n"
}

Service Result Code /authenticateUser

serviceResultCode	Description	HTTP code
0	User authenticated successfully.	200
-100	The registeredTemplateRaw parameter does not match the ID: [XXX]	200
-101	The bestImageToken parameter does not match a living person.	200
-102	User authentication failed due to non-matching templateRaw.	200