> 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/api-rest/identity-api/identity-api-reference/authentication/authenticate-user.md).

# Authenticate User

Este servicio valida tanto la prueba vida como la autenticación facial. Compara la plantilla biométrica, previamente validada y almacenada en el repositorio de datos del cliente durante el proceso de Onboarding, con un bestImageToken generado en el momento de la autenticación.

#### Funcionalidad

* **Primera llamada**: Establece un userId único para el usuario.
* **Autenticación**: En cada intento de autenticación, se envía el userId junto con la plantilla biométrica registrada. Esta plantilla se compara con la imagen tokenizada actual (bestImageToken). Si hay coincidencia y se supera la verificación de vida, el usuario se autentica exitosamente.

### Integración

Requiere la implementación del **widget Selphi Mobile** o del **widget Selphi Web** para generar el **bestImageToken** y la **plantilla biométrica (TemplateRaw)**.

### Endpoint

```
POST /services/authenticateUser
```

### Headers

| Nombre        | Tipo   | Requerido | Descripción                                                       |
| ------------- | ------ | --------- | ----------------------------------------------------------------- |
| **x-api-key** | string | **Sí**    | API key de autorización de acceso.                                |
| **family**    | string | No        | Valor: **Authentication**. Requerido con el servicio de tracking. |

{% hint style="info" %}
Todas las llamadas a los Endpoints para tracking con **Identity Platform** deben contener el header `family`.
{% endhint %}

### Cuerpo de la solicitud

**Content-Type:** `application/json`

#### Parámetros

| Parámetro               | Tipo   | Requerido | Descripción                                                                                                                                                                     |
| ----------------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`                | string | **Sí**    | Identificador único del usuario. Debe ser persistido y asociado con la plantilla biométrica correspondiente. Necesita al menos dos dígitos.                                     |
| `registeredTemplateRaw` | string | **Sí**    | Plantilla generada por el widget Selphi, cifrada con AES256 y tokenizada, enviada en formato Base64. Representa el patrón facial del usuario con la pose frontal más detectada. |
| `image`                 | string | No        | Imagen en formato Base64 obtenida del registro civil. Se vuelve obligatoria si no se proporciona la plantilla biométrica registrada (registeredTemplateRaw).                    |
| `bestImageToken`        | string | **Sí**    | Propiedad **bestImage tokenizada** generada por el widget Selphi en el momento de la autenticación.                                                                             |
| `template`              | string | No        | Plantilla biométrica en formato Base64. Se vuelve obligatoria si no se proporciona la bestImage tokenizada (bestImageToken).                                                    |
| `merchantReferenceId`   | string | **Sí**    | Referencia del cliente para cada autenticación. Se recomienda que este dato no contenga información sensible como PII (información de identificación personal).                 |
| `tracking`              | object | No        | Objeto que representa la información de seguimiento necesaria.                                                                                                                  |
| `tracking.extraData`    | string | No        | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma.                                                                         |
| `tracking.operationId`  | string | No        | Identificador de operación generado por el SDK Mobile/Web.                                                                                                                      |

#### Ejemplo de solicitud: Con plantilla biométrica registrada

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

#### Ejemplo de solicitud: Con imagen del registro civil

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

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                       | Tipo    | Descripción                                                                                                              |
| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `serviceResultCode`             | integer | Código que indica el **resultado general** de la ejecución del servicio. Ver [Service Result Code](#service-result-code) |
| `serviceResultLog`              | string  | Campo descriptivo del resultado de la ejecución. Incluye detalles cuando hay un error o excepción.                       |
| `serviceFacialSimilarityResult` | number  | Valor que indica la **similitud facial** entre el registeredTemplateRaw y el bestImageToken. **1.0 = 100%**              |
| `merchantReferenceId`           | string  | Referencia enviada en el cuerpo de la solicitud.                                                                         |
| `registeredTemplateRaw`         | string  | Plantilla biométrica registrada devuelta por el SDK SelphID para uso en autenticaciones posteriores.                     |
| `timestamp`                     | string  | Marca de tiempo (UTC) de la respuesta en formato YYYY-MM-DDThh:flag\_mm:ssZ                                              |
| `transactionId`                 | string  | Identificador de transacción asociado a la solicitud procesada por la API.                                               |

#### Service Result Code

El `serviceResultCode` indica el resultado general de la ejecución del servicio:

| serviceResultCode | Descripción                                                                          | Código HTTP |
| ----------------- | ------------------------------------------------------------------------------------ | ----------- |
| 0                 | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200         |

#### Service Result Code: Authenticate User

Códigos de resultado específicos del endpoint `authenticateUser`:

| serviceResultCode | Descripción                                                                   | Código HTTP |
| ----------------- | ----------------------------------------------------------------------------- | ----------- |
| 0                 | Usuario autenticado exitosamente.                                             | 200         |
| -100              | El parámetro `registeredTemplateRaw` no coincide con el ID: \[XXX]            | 200         |
| -101              | El parámetro `bestImageToken` no corresponde a una persona viva.              | 200         |
| -102              | La autenticación del usuario falló debido a que el `templateRaw` no coincide. | 200         |

#### Ejemplo de respuesta

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