> 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.md).

# 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. |

{% 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       | 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

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

#### Request example: 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 indicating the **overall result** of 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.                    |
| `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: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 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

```json
{
  "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

```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"
}
```