> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de autenticación biométrica: KYC sin contraseña

> Didit autentica a usuarios recurrentes con prueba de vida y coincidencia facial. Sin documentos, en menos de 2 segundos y sin contraseña. $0.10 por llamada.

La autenticación biométrica de Didit ofrece una experiencia de verificación ágil para usuarios recurrentes. Este flujo puede configurarse para hacer una comprobación solo de prueba de vida, como simple verificación de presencia, o para combinar la prueba de vida con el reconocimiento facial y obtener una confirmación de identidad más sólida frente a un retrato almacenado. Esta flexibilidad crea una experiencia sin fricciones sin renunciar a un alto nivel de seguridad.

Prompt de integración de la autenticación biométrica
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Biometric Authentication (passwordless re-verification of returning users) into your app.

\# Delivery mode
Biometric Authentication is **session-only**. There is no dedicated /v3/biometric-auth/ endpoint. It is delivered through a session whose workflow is configured for biometric-auth use (workflow_type=BIOMETRIC_AUTHENTICATION). Under the hood it reuses the same LivenessV3 + FaceMatchV3 serializers as the regular KYC flow — the only difference is the reference image source.

\# Reference image resolution (create time)
The reference face the live selfie is matched against comes from one of two places:
\- `portrait_image` (Base64, max 2MB) sent in the create-session request: always wins when provided.
\- Omitted `portrait_image`: Didit reuses a face already stored for the `vendor_data` user, resolved in this order: (1) face captured during an approved liveness check, (2) ePassport chip photo from an approved ID verification, (3) portrait cropped from the ID document of an approved ID verification, (4) a manually enrolled profile face (Users API / Console upload).
\- If `portrait_image` is omitted and the user has NO stored face, session creation fails with 400: {"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}
\- If `portrait_image` is omitted and `vendor_data` is missing too, session creation fails with 400: {"portrait_image": "A portrait image is required to perform face match for this workflow. Send a portrait_image, or provide the vendor_data of a user with a previously stored face image to reuse it."}

\# Steps
1\. Create a Biometric Auth workflow in the Business Console (workflow_type=BIOMETRIC_AUTHENTICATION). Configure the LIVENESS method (PASSIVE / ACTIVE_3D / FLASHING) and the FACE_MATCH similarity threshold.
2\. The returning user must already have a face on file under the same `vendor_data` (approved verification with liveness or ID document, or an enrolled profile face); otherwise send `portrait_image` explicitly.
3\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. Use the **same vendor_data** as the user's prior verification so the stored face can be retrieved. Add `portrait_image` only to override the stored face.
4\. Open session.url for the user (or mount the Web/Mobile SDK).
5\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_BIOMETRIC_AUTH_WORKFLOW_ID",
"vendor_data": "user-1234",
"callback": "https://yourapp.com/post-reauth"
}'
\```

\# Decision surface
Biometric Authentication surfaces results across **two arrays** on the decision payload — there is no biometric_auths[] array:
\- `liveness_checks[]` — the live capture (status + score + warnings under LogWarningChoices.LIVENESS).
\- `face_matches[]` — the comparison against the stored portrait (status + score + warnings under LogWarningChoices.FACEMATCH).

Approve the user only when **both** entries are status="Approved".

\# Status enum (per liveness_checks[].status and face_matches[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings
\- Liveness side (LogWarningChoices.LIVENESS): LOW_LIVENESS_SCORE, LIVENESS_FACE_ATTACK, NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED, FACE_IN_BLOCKLIST, DUPLICATED_FACE.
\- Face Match side (LogWarningChoices.FACEMATCH): LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE.
Full catalogue: /core-technology/biometric-auth/warnings-biometric-authentication.

\# Failure modes to handle
\- 400 on session creation with the "No stored face image was found for this user" message: the user has no stored face under this vendor_data; route them to first-time KYC, or send portrait_image explicitly.
\- NO_REFERENCE_IMAGE on face_matches[] — the reference image could not be resolved at match time; route the user to first-time KYC instead.
\- LOW_FACE_MATCH_SIMILARITY — the live selfie does not match the stored portrait; do not authenticate.
\- LIVENESS_FACE_ATTACK — presentation attack detected; reject and flag the account.
\- FACE_IN_BLOCKLIST — user has been added to your blocklist since enrolment; block.

\# See also
\- Canonical schema: /reference/data-models#biometric-authentication (and /reference/data-models#liveness-check, /reference/data-models#face-match)
\- Per-feature report: /core-technology/biometric-auth/report-biometric-authentication
\- Risk catalogue: /core-technology/biometric-auth/warnings-biometric-authentication
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

## Funciones principales#### Reverificación rápida- No hace falta escanear ningún documento
- Verificación completa en segundos
- Reduce la fricción y el abandono de los usuarios#### Seguridad avanzada- Usa la misma arquitectura de redes neuronales que la coincidencia facial 1:1
- Evita los intentos de apropiación de cuentas
- Incluye detección de prueba de vida para impedir la suplantación#### Flexibilidad de integración- Disponible en versión web
- Umbrales de coincidencia configurables
- Análisis de dispositivo e IP opcional para reforzar la seguridad## Cómo funciona**1. Creación de la sesión**Cuando creas una sesión de autenticación biométrica para un flujo con **coincidencia facial**, Didit necesita un rostro de referencia con el que comparar el selfie en vivo.
Tienes dos opciones:- **Enviar `portrait_image`** en Base64 (máx. 2MB) desde tu propia base de datos. Siempre tiene prioridad cuando se facilita.
- **Omitir `portrait_image`** y pasar el `vendor_data` del usuario. Didit reutiliza automáticamente el rostro ya almacenado de ese usuario, resuelto en este orden:
  1. Rostro capturado durante una **prueba de vida aprobada**
  2. **Foto del chip del pasaporte electrónico** de una verificación de identidad aprobada
  3. **Retrato recortado del documento de identidad** de una verificación de identidad aprobada
  4. **Rostro de perfil registrado manualmente** (API de usuarios o carga desde la Consola)```json theme={null}
{
  "workflow_id": "11111111-2222-3333-4444-555555555555",
  "vendor_data": "user-123",
  "callback": "https://example.com/verification/callback",
  "metadata": { "login_attempt": "2" }
}
```> [!WARNING]
>
> Solo se reutilizan rostros de sesiones **aprobadas** (o rostros que registraste tú mismo). Si omites `portrait_image` y el usuario no tiene un rostro almacenado, la creación de la sesión falla con `400` y el mensaje `No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first.` Si omites también `vendor_data`, el mensaje `400` te pide que envíes un `portrait_image` o un `vendor_data` con un rostro almacenado.**2. Captura de la foto en vivo**Durante el proceso de autenticación:| Comprobación | Descripción |
| - | - |
| **Verificación de prueba de vida** | Evita la suplantación con la prueba de vida pasiva o con Acción 3D y Flash |
| **Calidad de la imagen** | El sistema evalúa la iluminación, la posición y la nitidez |
| **Indicaciones para repetir** | Las imágenes de mala calidad se rechazan con instrucciones para mejorarlas |
| **Retroalimentación en tiempo real** | El usuario ve guías de posición para una captura óptima |**3. Verificación y procesamiento del resultado**El sistema procesa la verificación según la configuración de tu flujo:> **Modo solo prueba de vida**
>
> Si la **coincidencia facial está desactivada** en el flujo, el sistema solo confirma la prueba de vida del usuario; no hace falta un rostro de referencia ni `portrait_image`. Una comprobación correcta da como resultado una autenticación **aprobada**, útil para una simple verificación de presencia.> **Modo prueba de vida + coincidencia facial**
>
> Si la **coincidencia facial está activada** en el flujo (rostro de referencia de `portrait_image` o del rostro almacenado del usuario):
>
> 1. El sistema realiza primero la **comprobación de prueba de vida**
> 2. Si la prueba de vida se supera, compara el nuevo selfie con el rostro de referencia
> 3. Se genera una **puntuación de similitud (0–100%)**
> 4. Puntuación por encima del umbral configurado → **Aprobado**
> 5. Puntuación por debajo del umbral → **Rechazado**Los resultados están disponibles mediante la **respuesta de la API**, la **Business Console** y los **webhooks**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.