Authenticate User V2

This service validates both the liveness check and facial authentication. It compares the Biometric Template, previously validated and stored in the customer's data repository during the Onboarding process, with a bestImageToken generated at the time of authentication.

Functionality

• First call: Sets a unique userId for the user.

• Authentication: On 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.

Integration

Requires the implementation of the Selphi Mobile Widget or the Selphi Web Widget to generate the bestImageToken and the Biometric Template (TemplateRaw).

Endpoint

POST /services/authenticateUser/v2

Headers

Name	Type	Required	Description
x-api-key	string	Yes	API Key for access authorization.
family	string	No	Value: Authentication. Required with the tracking service.

All calls to the tracking Endpoints with Identity Platform must contain the header family.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
userId	string	Yes	Unique user identifier. It must be persisted and associated with the corresponding Biometric Template. It needs at least two digits.
registeredTemplateRaw	string	Yes	Template generated by the Selphi Widget, encrypted with AES256 and tokenized, sent in Base64 format. It represents the user's facial pattern with the most detected frontal pose.
image	string	No	Base64 image obtained from the civil registry. It becomes mandatory if the registered Biometric Template (registeredTemplateRaw) is not provided.
bestImageToken	string	Yes	Property tokenized bestImage generated by the Selphi Widget at the time of authentication.
template	string	No	Base64 Biometric Template. It becomes mandatory if the tokenized bestImage (bestImageToken) is not provided.
merchantReferenceId	string	Yes	Customer reference for each authentication. It is recommended that this data not contain sensitive information such as PII (personally identifiable information).
tracking	object	No	Object representing the necessary tracking information.
tracking.extraData	string	No	Token generated by the SDK Mobile/Web. Contains Tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the SDK Mobile/Web.

Request example: With registered Biometric Template

{
  "userId": "001",
  "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF...",
  "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...",
  "merchantReferenceId": "authenticate-001",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Request example: With image from the civil registry

{
  "userId": "001",
  "image": "/9j/4AAQ...",
  "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...",
  "merchantReferenceId": "authenticate-001",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceResultCode	integer	Code that indicates the overall result of the service execution. See Service Result Code
serviceResultLog	string	Descriptive field of the execution result. Includes details when there is an error or exception. If successful, it indicates the description of the result code.
serviceFacialSimilarityResult	number	Value indicating the facial similarity between the registeredTemplateRaw and the bestImageToken. 1.0 = 100%
serviceFacialAuthenticationLog	string	Descriptive field of the facial authentication result. Includes details when there is an error or exception in the module.
serviceFacialAuthenticationResult	integer	Code that indicates the facial authentication result. See Service Facial Authentication Result
serviceLivenessResult	integer	Code that indicates the passive liveness check result. See Service Liveness Result
serviceLivenessLog	string	Descriptive field of the passive liveness check result. Includes details when there is an error or exception.
merchantReferenceId	string	Reference sent in the request body.
registeredTemplateRaw	string	Registered Biometric Template returned by the SelphID SDK for use in subsequent authentications.
timestamp	string	Timestamp (UTC) of the response in format YYYY-MM-DDThh🇲🇲ssZ
transactionId	string	Transaction identifier associated with the request processed by the API.

Service Result Code

The serviceResultCode indicates the overall result of the service execution:

serviceResultCode	Description	HTTP code
0	The service execution was successful, the module processed the request correctly.	200

Service Liveness Result

The serviceLivenessResult indicates the result of the passive liveness check evaluation:

Code	Result	Description
0	None	The liveness check could not be evaluated.
1	Spoof	DEPRECATED. Use 'NoLive' instead.
2	Uncertain	DEPRECATED
3	Live	The subject is assumed to be alive.
4	NoneBecauseBadQuality	The liveness check could not be evaluated due to poor image quality.
5	NoneBecauseFaceTooClose	The liveness check could not be evaluated because the detected faces are too close to the edges.
6	NoneBecauseFaceNotFound	The liveness check could not be evaluated because no faces were detected.
7	NoneBecauseFaceTooSmall	The liveness check could not be evaluated because the detected faces are too small.
8	NoneBecauseAngleTooLarge	The liveness check could not be evaluated because the angle between faces exceeds the allowed limit.
9	NoneBecauseImageDataError	The liveness check could not be evaluated due to image format errors.
10	NoneBecauseInternalError	The liveness check could not be evaluated due to an internal error.
11	NoneBecauseImagePreprocessError	The liveness check could not be evaluated due to an image preprocessing error.
12	NoneBecauseTooManyFaces	The liveness check could not be evaluated because too many faces were detected in the image.
13	NoneBecauseFaceTooCloseToBorder	The liveness check could not be evaluated because the face is too close to the edge.
14	NoneBecauseFaceCropped	The liveness check could not be evaluated because the face is cropped.
15	NoneBecauseLicenseError	The liveness check could not be evaluated due to a license error.
16	NoneBecauseFaceOccluded	The liveness check could not be evaluated because the face is occluded.
17	NoLive	No life was detected.
18	NoneBecauseEyesClosed	The liveness check could not be evaluated because the person's eyes are closed.

Service Facial Authentication Result

The serviceFacialAuthenticationResult indicates the result of the facial matching operations:

Code	Result	Description
0	NONE	Facial verification could not be performed.
1	NEGATIVE	The process was executed successfully. The comparison of the facial pattern of the faces does not match.
3	POSITIVE	The process was executed successfully. The comparison of the facial pattern of the faces is positive. The value of serviceFacialSimilarityResult indicates the % similarity between the compared images.
4	NONE BECAUSE POSE EXCEED	Facial verification could not be performed due to the face position.
5	NONE BECAUSE INVALID EXTRACTIONS	Facial verification could not be performed due to problems in extracting the facial pattern.

Response example

{
  "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..."
}

400 Bad Request

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Bad Gateway

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
  "message": "Endpoint request timed out"
}