> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Guía de FACE AUTH
> Aprenda a usar el servicio complementario FACE AUTH que compara selfies con usuarios eKYC aprobados existentes para verificar si son la misma persona.
FACE AUTH es un **servicio complementario (add-on)** que verifica de forma inmediata si un usuario es la misma persona comparando la selfie (Referencia) de un Submission ID obtenido del eKYC existente con la selfie más reciente del usuario (Objetivo). Puede completar la reautenticación con una sola selfie sin un proceso complejo adicional.
## Casos de uso representativos
Como la identidad puede reverificarse con una sola selfie sin contraseña ni código de autenticación, puede reforzar la seguridad y reducir la fricción del usuario al mismo tiempo.
Usado por **instituciones financieras** como medio de reautenticación para reducir el riesgo de robo de cuentas durante el cambio de dispositivo o número.
**Prevención de ATO** - Aplique políticas de bloqueo/desbloqueo de acceso con autenticación facial adicional cuando se detecten inicios de sesión de alto riesgo, acceso desde el extranjero o intentos masivos.
**KYC Refresh periódico** - Utilizado como procedimiento de verificación periódica de la misma persona en servicios de alto valor o industrias reguladas.
Inserte como paso de verificación de identidad antes de cambios importantes en la cuenta, como restablecimiento de contraseña, cambio de método de pago o de contacto.
## Método de operación (3 pasos)
Debe existir un **Submission aprobado** de eKYC. (Referencia)
Llame a la URL del Add-On (incluyendo pid + Submission ID) → Tome la selfie
Al acceder desde escritorio, se muestra un QR → Continúe la captura en el móvil.
Comparación automática de registrado vs verificado → Los resultados se almacenan en el dashboard como **Auth ID** (submission).
**Verificaciones clave**
* Debe existir un Submission ID aprobado. (Referencia)
* La URL de FACE AUTH debe estar **cifrada por seguridad** al usarse.
* Las políticas de threshold, liveness y occlusion (mascarilla/casco/gorro, etc.) pueden controlarse a través de las opciones del proyecto.
## Beneficios de FACE AUTH
| Beneficio | Descripción |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Reautenticación rápida** | Complete con una sola selfie sin volver a fotografiar el ID |
| **Refuerzo de seguridad** | Proteja cuentas como factor adicional junto con contraseña y OTP |
| **Flexibilidad de políticas** | Ajustes detallados por situación como threshold de coincidencia facial, liveness, bloqueo por occlusion |
| **Integración sencilla** | Opera como add-on dependiente del proyecto eKYC existente, manteniendo consistencia operativa |
***
## Creación y configuración del proyecto
Para usar FACE AUTH, primero cree un proyecto Add-On en el dashboard y configure las políticas (threshold, liveness, occlusion).
### Paso 1: Crear proyecto Add-On
Seleccione **menú Add-On → 'Create Project'** en el dashboard para crear un nuevo proyecto FACE AUTH.
La conexión de dependencia con el proyecto eKYC se forma inmediatamente tras la creación, y la URL del Add-On y la API key se mapean automáticamente.
```
Path: Dashboard > Add-On > Create Project
```
### Paso 2: Configuración de información del proyecto
Especifique el nombre y logo del proyecto en la pantalla de configuración, y establezca el botón/URL para redirigir después de completar el envío de autenticación.
| Elemento de configuración | Descripción |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Project Name** | Se muestra como título en la pantalla de inicio de autenticación |
| **Project Status** | Service (operación normal) / Closed (autenticación desactivada) |
| **Add on Logo** | Se muestra en la parte superior de la primera pantalla de autenticación (se muestra el logo de ARGOS si no se configura) |
| **Return URL** | URL donde se redirige al usuario después de completar la autenticación |
### Paso 3: Configuración de políticas (Threshold)
Los thresholds son **más permisivos cuando son más bajos, más estrictos cuando son más altos**. Ajuste paso a paso para adaptarse a los objetivos de riesgo y UX del servicio.
| Elemento de política | Descripción | Valor recomendado |
| --------------------------------- | ---------------------------------------------------------------------------------------- | ----------------- |
| **Face Authentication Threshold** | Criterio para determinar si es la misma persona que la cara del usuario aprobado en eKYC | 98 puntos |
| **Liveness** | Determina si la selfie tomada es de una persona real viva (Passive/Active) | 70 puntos |
| **Face Occlusion** | Comprueba si el rostro no está ocluido por otros objetos durante la autenticación | - |
Face occlusion y face occlusion threshold **no pueden usarse simultáneamente**.
**Opciones para entornos especiales:**
* **Head Occlusion Threshold**: Entornos que requieren casco de seguridad (moto, obra, etc.)
* **Face Occlusion Threshold**: Entornos que requieren mascarilla (hospital, obra, etc.)
### Paso 4: Parámetros de URL del Add-On y configuración de cifrado
Se deben registrar los parámetros requeridos para usar la URL de FACE AUTH.
**Parámetros requeridos:**
| Parámetro | Descripción |
| --------- | ------------------------------------------------------------------------------------------------------- |
| `pid` | ID del proyecto Add-On (incluido en la ruta/parámetros de la URL) |
| `sid` | Submission ID de eKYC (la autenticación Add-On solo es posible en estado aprobado, se requiere cifrado) |
**Ejemplo de patrón de URL:**
```
...?pid={ADDON_PID}&encrypted={encrypted}
```
En la sentencia `encrypted`, use el Submission ID como `sid` y el Token ID como `token`.
#### Configuración de condiciones de expiración de Token
Puede configurar un control de acceso limitado a través del Token ID.
| Condición de expiración | Descripción |
| -------------------------- | --------------------------------------------------------------------- |
| **Usage-based Expiration** | Expira el Token ID cuando el token se usa una vez |
| **Time-based Expiration** | Mide el tiempo desde que el token se usa una vez y expira el Token ID |
La condición de activación de la expiración es cuando se hace **clic en el botón "Start"** en la primera pantalla de FACE AUTH.
***
## Provisión a usuarios
FACE AUTH puede proporcionarse de dos formas.
Guíe a los usuarios para abrir la URL del Add-On y proceder con la reautenticación mediante captura de selfie en la pantalla web.
**Parámetros requeridos:**
* `pid={AddOn Project ID}` — incluido en el query string de la URL en texto plano
* `encrypted={...}` — debe contener `sid={Submission ID aprobado de eKYC}` en su interior, cifrado con AES-256 (consulte [Paso 4](#paso-4-parámetros-de-url-del-add-on-y-configuración-de-cifrado))
```text Patrón de URL theme={null}
https://form.argosidentity.com/face-auth?pid={ADDON_PID}&encrypted={encrypted}
```
**Transición Escritorio → Móvil:**
Al abrirlo en PC, se muestra un código QR para que los usuarios lo escaneen con su teléfono y continúen la captura.
**Lista de verificación**
* ✅ Conecte la URL del Add-On a un enlace/botón
* ✅ Verifique que `sid` no falte y que la submission de eKYC esté en estado `approved`
* ✅ Los parámetros sensibles como `sid` deben incluirse dentro de `encrypted` — nunca expuestos en texto plano
* ✅ Si el tráfico de escritorio es alto, coloque texto guía de transición QR en posición fija superior
Exponga FACE AUTH en su propia UI con botones, modales o flujo por pasos, y llame al Add-On vía API desde el backend.
**Active Liveness no es compatible** cuando se procede con el método API.
* Especificaciones recomendadas de faceImage: 960 x 720
* Requiere una **API Key diferente** a la API Key del liveform existente.
**Lista de verificación**
* ✅ Verifique la creación del proyecto Add-On vinculado al historial de aprobación eKYC (copia registrada)
* ✅ Implemente lógica para pasar pid y submissionId al llamar
* ✅ Redirija al siguiente paso en callbacks de éxito/fallo
Consulte los métodos de integración basada en API en detalle.
### Verificación de operación (Smoke Test)
* Si aparece la pantalla de autenticación cuando se llama a la URL del Add-On con un submissionId aprobado
* Si la visualización del QR y la transición al móvil son naturales al acceder desde PC
* Si los resultados se almacenan y consultan como submission del Add-On (Auth ID) después de la captura
***
## AUTH ID - Verificación de resultado de autenticación
Auth ID se refiere a un resultado (submission) de FACE AUTH (add-on). Se registran juntos la evaluación de misma persona comparando la copia registrada (cara aprobada previamente de eKYC) con esta selfie (copia verificada), el snapshot de la política aplicada y la línea de tiempo del procesamiento.
### Ver resultados en el dashboard
```
Dashboard > Proyecto Add-On (FACE AUTH) > Lista de Submissions (Auth ID) > Vista de detalle
```
**Información visible en la pantalla de lista:**
* Hora
* AUTH ID (TARGET)
* Submission ID (Reference)
* Estado
**Información visible en la pantalla de detalle:**
* Snapshot de política
* Puntuación/threshold
* Resultados de liveness y occlusion
* Imágenes de comparación
* Logs
### Información detallada de Auth ID
| Campo | Descripción |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| **Authentication ID** | Identificador único del submission |
| **Submission ID** | Submission aprobado previamente referenciado como objetivo de comparación durante el submission |
| **Status** | Muestra el resultado de autenticación como Approved, Rejected |
| **Policy** | Opciones del proyecto aplicadas cuando se procesó el submission |
| **FACE Similarity** | Similitud entre imágenes de selfie medida durante la autenticación |
| **Liveness** | Puntuación de liveness de la selfie enviada |
| **Face Occluded** | Resultado que evalúa si el rostro está ocluido como Pass / Fail |
La información de referencia prioriza la comparación de Selfie, y si la Selfie no está disponible, utiliza el retrato del ID como secundario para la comparación.
***
## Integración en tiempo real vía Webhook
Cuando FACE AUTH finaliza y los resultados finales están disponibles, los resultados se **envían automáticamente a la URL de Webhook** registrada en el proyecto de ID Check existente.
Tipo de trigger: `"faceAuth"`
```json theme={null}
{
"webhook_trigger": "faceAuth",
"Authentication_id": "AUTH_...",
"data": {
"Submission_id": "SUB_...",
"Auth_Status": "approved | rejected",
"Create_Time": "UTC+0",
"User_id": "optional",
"cf1": "optional",
"cf2": "optional",
"cf3": "optional",
"reference": {
"userid": "optional",
"email": "optional",
"cf": { "cf1": "optional", "cf2": "optional", "cf3": "optional" }
}
}
}
```
**Lista de verificación de implementación**
* ✅ Registre la URL de Webhook (por unidad de proyecto) y confirme la recepción con respuesta 2xx
* ✅ Prevención de recepción duplicada: Verifique duplicados basándose en Authentication\_id
* ✅ Procesamiento de zona horaria: Create\_Time(UTC+0) → Convierta a hora estándar interna si es necesario
* ✅ Mapeo de claves: Mapee a usuarios/solicitudes internos con Submission\_id, User\_id, cf1\~3
* ✅ Registro de auditoría: Almacene el payload original y los resultados de enrutamiento juntos
Los administradores pueden consultar de forma operativa a través del dashboard, y los equipos de desarrollo pueden automatizar sistemas vía webhook simultáneamente. Consulte de forma consistente estado, puntuación, política y línea de tiempo por unidad de Auth ID, y conecte inmediatamente al flujo del sistema interno usando Authentication\_id/Submission\_id del webhook.
***
## Lista de verificación para adopción rápida
Cree el proyecto FACE AUTH en Dashboard → Add-On.
Configure face match threshold / liveness / bloqueo por occlusion (ON/OFF).
Se requiere un Submission de eKYC aprobado para usar como Referencia.
Incluya pid + Submission ID en la URL del Add-On (considere el flujo escritorio→QR→móvil)
Monitorice el estado, política y resultados de comparación de Auth ID (submission) en el dashboard.
### Consejos de operación
* Comience con valores iniciales de política algo **conservadores** → Ajuste gradualmente los thresholds mientras revisa los datos reales del servicio
* **Métricas de monitoreo**: Tasa de éxito de reautenticación, tasa de abandono, tiempo promedio de autenticación, tasa de bloqueo de eventos de riesgo, tasa de completación de restablecimiento/cambio
* **Diseño UX**: Si la tasa de acceso desde escritorio es alta, guíe claramente el flujo de transición QR, y proporcione una guía de autenticación con texto mínimo para usuarios móviles
***
## Documentación relacionada
Consulte la descripción general completa del servicio Add-On.
Aprenda a integrar FACE AUTH vía API.
Aprenda a recibir resultados de FACE AUTH vía webhook.
Aprenda métodos de cifrado de URL.