> 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 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 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** | Access authorization API Key. | | **family** | string | No | Value: **Authentication**. Required with the Tracking service. | {% hint style="info" %} All calls to the Endpoints for Tracking 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 | Biometric Template in Base64 format. 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 required tracking information. | | `tracking.extraData` | string | No | Token generated by the SDK Mobile/Web. It contains tokenized tracking information with the Platform. | | `tracking.operationId` | string | No | Operation identifier generated by the SDK Mobile/Web. | #### Example request: With registered biometric template ```json { "userId": "001", "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF...", "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...", "merchantReferenceId": "authenticate-001", "tracking": { "extraData": "BQABAQG2gBNjuHN...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` #### Example request: With civil registry image ```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 that indicates 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 **result of the passive liveness check**. 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 YYYY-MM-DDThh format: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 permitted limit. | | 9 | NoneBecauseImageDataError | The liveness check could not be evaluated due to errors in the image format. | | 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 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 facial matching operations: | Code | Result | Description | | ---- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | NONE | Facial verification could not be performed. | | 1 | NEGATIVE | The process executed successfully. The face pattern comparison did not match. | | 3 | POSITIVE | The process executed successfully. The face pattern comparison 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 extracting the face 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" } ```