Comenzar con FaceAuth - ARGOS Identity

La API de FaceAuth se ha trasladado a /v3/face-auth.La ruta, la estructura de la respuesta, los nombres de los campos y el formato de error difieren del endpoint anterior /v3/faceauth. Para migrar una integración existente, consulte Referencia común de FaceAuth — Migrar desde la API anterior. El método FaceAuth URL (https://form.argosidentity.com/face-auth) no se ve afectado por este cambio.

Las URL de Liveform de esta página corresponden a proyectos de la región US. Los proyectos de la región KR usan el host form-kr.argosidentity.com. Consulte Regiones para más detalles.

Lectura relacionada

Crear un proyecto FaceAuth en el panel y configurar la política (umbrales, liveness, oclusión) y la expiración del token → Guía de FaceAuth
Aspectos comunes a todos los complementos (emisión de la clave API, cuotas de solicitudes, códigos de estado de respuesta HTTP) → Comenzar con complementos

Modos de entrega de FaceAuth — 2 opciones

FaceAuth puede entregarse de dos formas. Recomendamos el método FaceAuth URL, que elimina la necesidad de implementar una UI de cámara propia y admite Active Liveness.

A. FaceAuth URL (Recomendado)

La captura del selfie se realiza en una página alojada por ARGOS (similar a Liveform). No es necesario implementar una UI de cámara en el cliente, y la política del proyecto puede habilitar Liveness (Pasivo/Activo) y controles de oclusión (mascarilla/casco).

B. POST /v3/face-auth API

Su aplicación implementa la UI de cámara y envía el archivo faceImage capturado al API. Active Liveness no es compatible — solo se compara la similitud facial.

Si le preocupan los intentos de suplantación (replays de pantalla, fotos impresas), utilice el método URL. El método POST API juzga una sola imagen enviada únicamente por similitud y no puede verificar que el usuario esté físicamente presente. El método URL le permite configurar un umbral de Liveness en la política del proyecto para bloquear ataques de replay de pantalla y fotos estáticas.

Para la configuración de políticas en el dashboard (umbrales, liveness, oclusión) y casos de uso de ambos métodos, consulte la Guía de FaceAuth. El resto de esta página cubre los parámetros y el flujo de autenticación del Método A (FaceAuth URL). Para el Método B (POST API), consulte la página POST/Face-auth.

Query String para acceder a FaceAuth

FaceAuth es un subproyecto de ID check, y los administradores pueden crear tantos proyectos como deseen. Para entregar autenticación adicional mediante el método FaceAuth URL, utilice la URL de FaceAuth dentro del proyecto Add-on.
Para hacer referencia a un submission_Id que ha sido aprobado a través de ID document o Knowledge-based donde existe una imagen selfie, se debe agregar a la URL mediante el parámetro de consulta encrypted, y por motivos de seguridad, siempre debe usarse en estado cifrado.
El cifrado debe utilizar la clave API dentro del proyecto FaceAuth y utiliza AES-256.
Para métodos detallados, consulte Cifrado de Cadena de Consulta.

El texto plano que se cifra es JSON — no una cadena de consulta.Si cifra una cadena formada por pares key=value unidos con & (por ejemplo sid=...&authUserId=...), el sid no se reconoce y la verificación no se inicia. Serialice un objeto JSON (JSON.stringify) y cifre esa cadena, y use el resultado como valor de encrypted.En ese caso la pantalla muestra “Página no encontrada” en lugar de una página con código de error, lo que dificulta identificar la causa. Para el orden de diagnóstico, consulte Validación de la URL de FaceAuth y manejo de errores.

FaceAuth no se ejecuta sin cadena de consulta.Una URL que solo lleve pid no inicia la verificación — el sid de referencia debe cifrarse y enviarse dentro de encrypted. Si falta, el usuario es redirigido a la página de error PV-40015.

Paso 1 — Prepare el texto plano (JSON) que va a cifrar

{
  "sid": "{submission_Id}"
}

{
  "sid": "{submission_Id}",
  "authUserId": "{user Id}",
  "authCf1": "{additional_info}",
  "authCf2": "{additional_info}",
  "authCf3": "{additional_info}",
  "token": "{any tokenId}"
}

Paso 2 — Cifre con la clave API del proyecto FaceAuth (AES-256) y construya la URL

Estructura de la URL de FaceAuth (esta forma por sí sola no se ejecuta)

  Región US: https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}
  Región KR: https://form-kr.argosidentity.com/face-auth?pid={faceAuth_projectId}

El valor cifrado enviado en encrypted (forma ejecutable)

  Región US: https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={encrypted}
  Región KR: https://form-kr.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={encrypted}

El valor de encrypted debe estar codificado para URL.El resultado del cifrado AES-256 (Base64) contiene +, / y =. Si lo añade a la URL sin codificar, + se interpreta como un espacio, por lo que el descifrado falla y no se puede leer el sid. Aplique encodeURIComponent (o la función de codificación de URL de su lenguaje).

Ejemplo completo en Node.js

const crypto = require('crypto');

function encrypt(data, apiKey) {
  const hashedKey = crypto.createHash('sha256').update(apiKey).digest();
  const cipher = crypto.createCipheriv('aes-256-ecb', hashedKey, null);
  return cipher.update(data, 'utf8', 'base64') + cipher.final('base64');
}

// Paso 1: el texto plano es un objeto JSON serializado
const queryData = JSON.stringify({
  sid: 'submission_12345',
  authUserId: 'user123',
});

// Paso 2: cifre con la clave API del proyecto FaceAuth y codifique para URL
const encrypted = encrypt(queryData, FACEAUTH_API_KEY);
// Región KR: https://form-kr.argosidentity.com
const faceAuthUrl =
  `https://form.argosidentity.com/face-auth?pid=${FACEAUTH_PROJECT_ID}` +
  `&encrypted=${encodeURIComponent(encrypted)}`;

pid y lang no están sujetos a cifrado — añádalos como texto plano fuera de encrypted.

Definición de parámetros de solicitud

string

requerido

Número único asignado al proyecto al crear un proyecto FaceAuth (se adjunta automáticamente a la URL)

string

requerido

submission_Id aprobado a través de ID document o Knowledge-based (se usa sid para distinguir)

string

ID de usuario que el administrador asignará al usuario (puede ser el ID de usuario en el servicio del administrador o el mismo userId utilizado en ID document o Knowledge-based)

string

Información adicional que el administrador asignará al usuario (por ejemplo, dirección de correo electrónico, etc.)

string

Información adicional que el administrador asignará al usuario (igual que authCf1)

string

Información adicional que el administrador asignará al usuario (igual que authCf1)

string

Token que el administrador agregará a la URL con fines de seguridad.
¡Nota!: Este token opera de forma independiente del token preregistrado en modo privado.

Cómo funciona el token de FaceAuth

El token está diseñado para asignar una URL única a cada usuario cuando se autentican a través de FaceAuth.
Para aplicar un token, debe habilitar la opción de configuración de condición de expiración de token en el proyecto FaceAuth, y funciona de la siguiente manera:

Expiración basada en conteo: Cuando el token se usa una vez, el Token ID expira inmediatamente.
Expiración basada en tiempo: Cuando ha transcurrido el tiempo desde el momento en que el token se usó una vez, el Token ID expira.

Este token opera de forma independiente del token de modo privado del proyecto principal o del token preregistrado.
Por ejemplo, puede especificar un tokenId arbitrario establecido por el administrador en el token, e incluso si reutiliza el token usado en el proyecto principal, funciona porque se gestiona por separado. Para una guía sobre cómo habilitar la opción de configuración de condición de expiración de token en el proyecto FaceAuth, consulte Guía de FaceAuth — Configuración de condiciones de expiración de Token.

string

Idioma de visualización de la pantalla de FaceAuth. Use un código ISO 639-1 en minúsculas (por ejemplo, en, ko). No está sujeto a cifrado — añádalo en texto plano fuera de encrypted (por ejemplo, ?pid={faceAuth_projectId}&encrypted={encrypted}&lang=en). Si se omite, en móvil se usa el idioma del dispositivo y en PC el del navegador. Para la lista de idiomas admitidos, consulte Idiomas Soportados.

Para casos aprobados donde no existe imagen selfie, se utilizará en su lugar la imagen de retrato del documento de identidad.

URL de retorno

La tarjeta AddOn Return URL de la configuración del proyecto FaceAuth define a dónde vuelve el usuario tras la autenticación y qué campos se envían con él. Los campos seleccionados se añaden a la consulta de la URL de retorno en el orden mostrado en la pantalla de configuración.

string

Resultado de autenticación: approved o rejected. (Authentication Result en la pantalla de configuración)

string

Clave del envío de FaceAuth. (Authentication ID en la pantalla de configuración) Se usa tal cual en las API de consulta individual, descarga de imagen y eliminación.

string

ID de usuario que envió dentro de encrypted en la entrada. (User ID en la pantalla de configuración)

string

Campo personalizado #1 enviado en la entrada.

string

Campo personalizado #2 enviado en la entrada.

string

Campo personalizado #3 enviado en la entrada.

Ejemplo de URL de retorno

https://yourapp.com/callback?authStatus={authStatus}&authId={authId}&authUserId={authUserId}&authCf1={authCf1}&authCf3={authCf3}

Los campos no marcados se omiten de la consulta. El ejemplo anterior corresponde a no haber seleccionado el campo personalizado #2.

Omitir la página de resultado

Al activar Skip Result Page, el usuario va directamente a la URL de retorno sin ver la pantalla de resultado de FaceAuth. La opción no tiene efecto si no hay una URL de retorno configurada.

Cifrado

Al activar Encryption, los campos seleccionados se agrupan en un único parámetro encrypted. Descífrelo con AES-256-ECB, el mismo esquema que la URL de retorno de ID check. → Guía de cifrado y descifrado

Nunca considere los parámetros de la URL de retorno como prueba suficiente de una autenticación correcta. Los valores pasan por el navegador del usuario y pueden manipularse. Vuelva a comprobar el resultado en el servidor llamando a la API de consulta individual con authId, o use el webhook de FaceAuth.

La URL de retorno de ID check (Liveform) se gestiona por separado en Información de integración > URL de retorno del proyecto principal y envía parámetros distintos (submissionId, kycStatus, entre otros). Ambas configuraciones son independientes. → Guía de URL de retornoPara saber dónde configurarla en el panel, consulte la Guía de FaceAuth.

Validación y manejo de errores de FaceAuth URL

Referencia por etapas de los códigos de error generados por fallos de validación de query string, fallos de precarga y fallos de autenticación, junto con los mensajes que los usuarios ven realmente.

Endpoints de la API de FaceAuth

La ruta base de todos los endpoints es https://rest-api.argosidentity.com/v3/face-auth en los proyectos de la región US y https://kr.rest-api.argosidentity.com/v3/face-auth en los de la región KR.

POST /v3/face-auth

Crear un envío de FaceAuth

GET /v3/face-auth

Consultar la lista de envíos

GET /v3/face-auth/{authId}

Consultar un envío individual

GET /v3/face-auth/{authId}/image

Descargar la imagen facial

DELETE /v3/face-auth/{authId}

Eliminar un envío

Referencia común de FaceAuth

Objeto de respuesta, formato de error y migración

Webhooks

FaceAuth

Webhook de FaceAuth

Expiración de Token ID

Webhook de expiración de Token ID

​Modos de entrega de FaceAuth — 2 opciones

A. FaceAuth URL (Recomendado)

B. POST /v3/face-auth API

​Query String para acceder a FaceAuth

​Paso 1 — Prepare el texto plano (JSON) que va a cifrar

​Paso 2 — Cifre con la clave API del proyecto FaceAuth (AES-256) y construya la URL

​Definición de parámetros de solicitud

​URL de retorno

​Omitir la página de resultado

​Cifrado

Validación y manejo de errores de FaceAuth URL

​Endpoints de la API de FaceAuth

POST /v3/face-auth

GET /v3/face-auth

GET /v3/face-auth/{authId}

GET /v3/face-auth/{authId}/image

DELETE /v3/face-auth/{authId}

Referencia común de FaceAuth

​Webhooks

FaceAuth

Expiración de Token ID

Modos de entrega de FaceAuth — 2 opciones

Query String para acceder a FaceAuth

Paso 1 — Prepare el texto plano (JSON) que va a cifrar

Paso 2 — Cifre con la clave API del proyecto FaceAuth (AES-256) y construya la URL

Definición de parámetros de solicitud

URL de retorno

Omitir la página de resultado

Cifrado

Endpoints de la API de FaceAuth

Webhooks