> ## 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 d'autenticació biomètrica: KYC sense contrasenya

> Didit autentica usuaris recurrents amb prova de vida i coincidència facial sense documents ni contrasenya en menys de 2 s. $0.10 per crida.

La solució d'Autenticació biomètrica de Didit proporciona una experiència de verificació optimitzada per a usuaris recurrents. Aquest flux de treball es pot configurar per dur a terme una comprovació només de prova de vida per a una verificació de presència senzilla, o bé combinar la prova de vida amb reconeixement facial per a una confirmació d'identitat més sòlida contrastant-la amb un retrat emmagatzemat. Aquesta flexibilitat crea una experiència sense fricció alhora que manté uns estàndards de seguretat elevats.

Indicació d'integració de l'autenticació biomètrica
        Copia el prompt al porta-retalls



      
      

\<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>



      
      

Enganxa a

## Funcionalitats principals#### Reverificació ràpida- No requereix escanejar cap document
- Verificació completa en qüestió de segons
- Redueix la fricció de l'usuari i l'abandonament#### Seguretat avançada- Utilitza la mateixa arquitectura de xarxa neuronal que Coincidència facial 1:1
- Prevé intents de robatori de comptes
- Inclou prova de vida per prevenir la suplantació#### Flexibilitat d'integració- Disponible com a solució basada en web
- Llindars de coincidència configurables
- Anàlisi de dispositiu i IP opcional per a una seguretat millorada## Com funciona**1. Creació de la sessió**Quan crees una sessió d'autenticació biomètrica per a un flux de treball amb **coincidència facial**, Didit necessita una cara de referència per comparar-hi la selfie en directe.
Tens dues opcions:- **Enviar `portrait_image`** en Base64 (màx. 2MB) des de la teva pròpia base de dades. Sempre té prioritat quan es proporciona.
- **Ometre `portrait_image`** i passar el `vendor_data` de l'usuari. Didit reutilitza automàticament la cara que ja està emmagatzemada per a aquest usuari, resolta en aquest ordre:
  1. Cara capturada durant una **comprovació de prova de vida aprovada**
  2. **Foto del xip del passaport electrònic** d'una verificació d'identitat aprovada
  3. **Retrat retallat del document d'identitat** d'una verificació d'identitat aprovada
  4. **Cara de perfil registrada manualment** (Users API o càrrega a 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]
>
> Només es reutilitzen les cares de sessions **aprovades** (o cares que hagis registrat tu mateix). Si omets `portrait_image` i l'usuari no té cap cara emmagatzemada, la creació de la sessió falla amb `400` i el missatge `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 també omets `vendor_data`, el missatge de l'`400` et demana que enviïs un `portrait_image` o un `vendor_data` amb una cara emmagatzemada.**2. Captura de la foto en directe**Durant el procés d'autenticació:| Comprovació | Descripció |
| - | - |
| **Verificació de prova de vida** | Prevé la suplantació mitjançant Passive Liveness o 3D Action & Flash |
| **Qualitat de la imatge** | El sistema avalua la il·luminació, el posicionament i la claredat |
| **Indicacions per reintentar** | Les imatges de mala qualitat es rebutgen amb instruccions de millora |
| **Comentaris en temps real** | L'usuari veu guies de posicionament per a una captura òptima |**3. Verificació i processament del resultat**El sistema processa la verificació segons la configuració del teu flux de treball:> [accordion] Mode només de prova de vida
>
> Si la **Coincidència facial està desactivada** al flux de treball, el sistema només confirma la prova de vida de l'usuari; no cal cap cara de referència i `portrait_image` no és necessari. Una comprovació satisfactòria dona com a resultat una autenticació en estat **aprovada**, útil per a una verificació de presència senzilla.> [accordion] Mode de prova de vida + coincidència facial
>
> Si la **Coincidència facial està activada** al flux de treball (cara de referència procedent de `portrait_image` o de la cara emmagatzemada de l'usuari):
>
> 1. El sistema realitza primer la **comprovació de prova de vida**
> 2. Si la prova de vida es supera, compara la nova selfie amb la cara de referència
> 3. Es genera una **puntuació de similitud (0–100%)**
> 4. Puntuació per sobre del teu llindar configurat → **Aprovada**
> 5. Puntuació per sota del llindar → **Rebutjada**Els resultats estan disponibles mitjançant la **resposta de l'API**, la **Business Console** i els **webhooks**.


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