Authenticate User

This service validates both liveness 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 together with the registered biometric template. This template is compared with the current tokenized image (bestImageToken). If there is a match and liveness verification is passed, the user is authenticated successfully.

Integration

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

Endpoint

POST /services/authenticateUser

Headers

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

All calls to the Endpoints for Tracking 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 that represents the necessary tracking information.
tracking.extraData	string	No	Token generated by the Mobile/Web SDK. Contains tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the Mobile/Web SDK.

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 civil registry image

{
  "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 indicating the overall result of service execution. See Service Result Code
serviceResultLog	string	Descriptive field of the execution result. Includes details when there is an error or exception.
serviceFacialSimilarityResult	number	Value indicating the facial similarity between the registeredTemplateRaw and the bestImageToken. 1.0 = 100%
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 Result Code: Authenticate User

Specific result codes for the Endpoint authenticateUser:

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

Response example

{
  "merchantReferenceId": "82b0084f-ddec-4415-8d2f-b085b42a0155",
  "serviceResultCode": 0,
  "serviceResultLog": "",
  "serviceFacialSimilarityResult": 0.9946970343589783,
  "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"
}