> ## 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'authentification biométrique sans mot de passe

> Authentifiez les utilisateurs sans document avec Didit : détection du vivant et correspondance faciale en moins de 2 s sans mot de passe. $0.10/appel.

La solution d'Authentification biométrique de Didit offre une expérience de vérification rationalisée pour les utilisateurs récurrents. Ce workflow peut être configuré pour effectuer un contrôle de détection du vivant seul afin de vérifier simplement la présence, ou combiner la détection du vivant avec la reconnaissance faciale pour une confirmation d'identité renforcée par rapport à un portrait stocké. Cette flexibilité crée une expérience sans friction tout en maintenant des normes de sécurité élevées.

Prompt d'intégration de l'authentification biométrique
        Copier le prompt dans le presse-papiers



      
      

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



      
      

Coller dans

## Principales fonctionnalités#### Revérification rapide- Aucun scan de document requis
- Vérification complète en quelques secondes
- Réduit les frictions pour l'utilisateur et les abandons#### Sécurité avancée- Utilise la même architecture de réseau neuronal que Correspondance faciale 1:1
- Prévient les tentatives de prise de contrôle de compte
- Comprend la détection du vivant pour prévenir l'usurpation#### Flexibilité d'intégration- Disponible en version Web
- Seuils de correspondance configurables
- Analyse de l'appareil et de l'IP optionnelle pour une sécurité renforcée## Comment ça fonctionne**1. Création de la session**Lorsque vous créez une session d'authentification biométrique pour un workflow avec **correspondance faciale**, Didit a besoin d'un visage de référence auquel comparer le selfie en direct.
Vous disposez de deux options :- **Envoyer `portrait_image`** en Base64 (2MB max) depuis votre propre base de données. Il a toujours la priorité lorsqu'il est fourni.
- **Omettre `portrait_image`** et transmettre le `vendor_data` de l'utilisateur. Didit réutilise automatiquement le visage déjà stocké pour cet utilisateur, selon l'ordre suivant :
  1. Visage capturé lors d'un **contrôle de détection du vivant approuvé**
  2. **Photo de la puce du passeport électronique** issue d'une vérification d'identité approuvée
  3. **Portrait recadré du document d'identité** d'une vérification d'identité approuvée
  4. **Visage de profil enregistré manuellement** (API Users ou importation dans la 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]
>
> Seuls les visages issus de sessions **approuvées** (ou les visages que vous avez vous-même enregistrés) sont réutilisés. Si vous omettez `portrait_image` et que l'utilisateur n'a aucun visage stocké, la création de la session échoue avec une erreur `400` et le message `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 vous omettez également `vendor_data`, le message `400` vous demande d'envoyer un `portrait_image` ou un `vendor_data` disposant d'un visage stocké.**2. Capture de la photo en direct**Pendant le processus d'authentification :| Vérification | Description |
| - | - |
| **Vérification de la détection du vivant** | Prévient l'usurpation à l'aide de la détection passive ou 3D Action & Flash |
| **Qualité de l'image** | Le système évalue l'éclairage, le positionnement et la netteté |
| **Conseils pour réessayer** | Les images de mauvaise qualité sont rejetées avec des instructions d'amélioration |
| **Retour en temps réel** | L'utilisateur voit des guides de positionnement pour une capture optimale |**3. Vérification et traitement des résultats**Le système traite la vérification en fonction de la configuration de votre workflow :> [accordion] Mode de détection du vivant uniquement
>
> Si **la correspondance faciale est désactivée** dans le workflow, le système confirme uniquement que l'utilisateur est bien vivant ; aucun visage de référence n'est requis et `portrait_image` n'est pas nécessaire. Un contrôle réussi débouche sur une authentification **approuvée**, utile pour une simple vérification de présence.> [accordion] Mode Détection du vivant + Correspondance faciale
>
> Si **la correspondance faciale est activée** dans le workflow (visage de référence issu de `portrait_image` ou du visage stocké de l'utilisateur) :
>
> 1. Le système effectue d'abord le **contrôle de détection du vivant**
> 2. Si la détection du vivant est réussie, il compare le nouveau selfie au visage de référence
> 3. Un **score de similarité (0–100%)** est généré
> 4. Score supérieur à votre seuil configuré → **Approuvé**
> 5. Score inférieur au seuil → **Refusé**Les résultats sont disponibles via la **réponse de l'API**, la **Business Console** et les **webhooks**.


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