> ## 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 di autenticazione biometrica: KYC senza password

> Autentica utenti con Didit tramite vitalità e confronto facciale: verifica senza password in meno di 2s, senza documenti. Pay-per-call da $0.10.

La soluzione di Autenticazione biometrica di Didit offre un'esperienza di verifica semplificata per gli utenti abituali. Questo workflow può essere configurato per eseguire un controllo di sola vitalità per una semplice verifica della presenza, oppure combinare la vitalità con il riconoscimento facciale per una conferma dell'identità più robusta rispetto a una foto salvata. Questa flessibilità garantisce un'esperienza senza attriti mantenendo elevati standard di sicurezza.

Prompt per l'integrazione dell'autenticazione biometrica
        Copia il prompt negli appunti



      
      

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



      
      

Incolla in

## Funzionalità principali#### Nuova verifica rapida- Nessuna scansione di documenti richiesta
- Completa la verifica in pochi secondi
- Riduce l'attrito per l'utente e il tasso di abbandono#### Sicurezza avanzata- Utilizza la stessa architettura di rete neurale del Confronto facciale 1:1
- Previene i tentativi di appropriazione dell'account
- Include il rilevamento della vitalità per prevenire lo spoofing#### Flessibilità di integrazione- Disponibile via web
- Soglie di corrispondenza configurabili
- Analisi dispositivo e IP opzionale per una maggiore sicurezza## Come funziona**1. Creazione della sessione**Quando crei una sessione di autenticazione biometrica per un workflow con **confronto facciale**, Didit ha bisogno di un volto di riferimento con cui confrontare il selfie live.
Hai due opzioni:- **Inviare `portrait_image`** in Base64 (max 2MB) dal tuo database. Ha sempre la precedenza quando viene fornito.
- **Omettere `portrait_image`** e passare il `vendor_data` dell'utente. Didit riutilizza automaticamente il volto già memorizzato per quell'utente, individuato nel seguente ordine:
  1. Volto acquisito durante un **controllo di vitalità approvato**
  2. **Foto del chip del passaporto elettronico (ePassport)** da una verifica dell'identità approvata
  3. **Ritratto ritagliato dal documento di identità** di una verifica dell'identità approvata
  4. **Volto del profilo registrato manualmente** (chiamata alle Users API o caricamento da Console)```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]
>
> Vengono riutilizzati solo i volti provenienti da sessioni **approvate** (o volti registrati direttamente da te). Se ometti `portrait_image` e l'utente non ha alcun volto memorizzato, la creazione della sessione fallisce con `400` e il messaggio `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.` Se ometti anche `vendor_data`, il messaggio `400` richiede di inviare un `portrait_image` o un `vendor_data` con un volto memorizzato.**2. Acquisizione della foto live**Durante il processo di autenticazione:| Controllo | Descrizione |
| - | - |
| **Verifica della vitalità** | Previene lo spoofing mediante vitalità passiva o 3D Action & Flash |
| **Qualità dell'immagine** | Il sistema valuta l'illuminazione, il posizionamento e la nitidezza |
| **Indicazioni per riprovare** | Le immagini di scarsa qualità vengono rifiutate con istruzioni di miglioramento |
| **Feedback in tempo reale** | L'utente visualizza guide di posizionamento per un'acquisizione ottimale |**3. Verifica ed elaborazione del risultato**Il sistema elabora la verifica in base alla configurazione del tuo workflow:> [accordion] Modalità di sola vitalità
>
> Se il **Confronto facciale è disabilitato** nel workflow, il sistema conferma solo la vitalità dell'utente; non è necessario alcun volto di riferimento e `portrait_image` non è richiesto. Un controllo riuscito produce un'autenticazione **approvata**, utile per una semplice verifica della presenza.> [accordion] Modalità vitalità + Confronto facciale
>
> Se il **Confronto facciale è abilitato** nel workflow (volto di riferimento ottenuto da `portrait_image` o dal volto memorizzato dell'utente):
>
> 1. Il sistema esegue prima il **controllo di vitalità**
> 2. Se il controllo di vitalità ha esito positivo, confronta il nuovo selfie con il volto di riferimento
> 3. Viene generato un **punteggio di somiglianza (0–100%)**
> 4. Punteggio superiore alla soglia configurata → **Approvata**
> 5. Punteggio inferiore alla soglia → **Rifiutata**I risultati sono disponibili tramite **risposta API**, **Business Console** e **webhook**.


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