> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/authentication/authenticate-user-v2.md). # 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. | {% hint style="info" %} All calls to the tracking Endpoints with **Identity Platform** must contain the header `family`. {% endhint %} ### 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 ```json { "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 ```json { "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](#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](#service-facial-authentication-result) | | `serviceLivenessResult` | integer | Code that indicates the **passive liveness check result**. See [Service Liveness Result](#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:flag\_mm: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 ```json { "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 ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Unauthorized ```json { "message": "Unauthorized" } ``` #### `403` Forbidden ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Bad Gateway ```json { "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 ```json { "message": "Endpoint request timed out" } ```