> ## 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.

# Biometrische Authentifizierung: API für passwortloses KYC

> Wiederkehrende Nutzer per Liveness-Erkennung & Gesichtsabgleich mit Didit verifizieren. Ohne Dokumente, unter 2 Sek., Pay-per-call $0.10.

Die Lösung für die biometrische Authentifizierung von Didit bietet ein optimiertes Verifizierungserlebnis für wiederkehrende Benutzer. Dieser Workflow kann so konfiguriert werden, dass er eine reine Liveness-Prüfung für eine einfache Anwesenheitsverifizierung durchführt oder Liveness mit Gesichtserkennung für einen stärkeren Identitätsabgleich mit einem gespeicherten Porträt kombiniert. Diese Flexibilität sorgt für ein reibungsloses Erlebnis bei gleichzeitig hohen Sicherheitsstandards.

Prompt zur Integration der biometrischen Authentifizierung
        Prompt in die Zwischenablage kopieren



      
      

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



      
      

Einfügen in

## Wichtigste Funktionen#### Schnelle erneute Verifizierung- Kein Scannen von Dokumenten erforderlich
- Vollständige Verifizierung in Sekundenschnelle
- Verringert Reibungsverluste und Abbrüche auf Benutzerseite#### Erweiterte Sicherheit- Verwendet dieselbe neuronale Netzwerkarchitektur wie Face Match 1:1
- Verhindert Versuche der Kontoübernahme
- Beinhaltet Liveness-Erkennung zur Abwehr von Spoofing#### Flexible Integration- Web-basiert verfügbar
- Konfigurierbare Schwellenwerte für den Abgleich
- Optionale Geräte- und IP-Analyse für erhöhte Sicherheit## Wie es funktioniert**1. Sitzungserstellung**Wenn Sie eine Sitzung zur biometrischen Authentifizierung für einen Workflow mit **Gesichtsabgleich** erstellen, benötigt Didit ein Referenzgesicht, mit dem das Live-Selfie verglichen werden kann.
Sie haben zwei Optionen:- **Senden Sie `portrait_image`** in Base64 (max 2MB) aus Ihrer eigenen Datenbank. Sofern angegeben, hat dies stets Vorrang.
- **Lassen Sie `portrait_image` weg** und übergeben Sie die `vendor_data` des Benutzers. Didit verwendet automatisch das bereits für diesen Benutzer gespeicherte Gesicht wieder, ermittelt in der folgenden Reihenfolge:
  1. Gesicht, das während einer **genehmigten Liveness-Prüfung** erfasst wurde
  2. **Foto vom ePass-Chip** aus einer genehmigten Ausweisverifizierung
  3. **Aus dem Ausweisdokument zugeschnittenes Porträt** einer genehmigten Ausweisverifizierung
  4. **Manuell registriertes Profilgesicht** (Users API oder Console-Upload)```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]
>
> Es werden ausschließlich Gesichter aus **genehmigten** Sitzungen (oder von Ihnen selbst registrierte Gesichter) wiederverwendet. Wenn Sie `portrait_image` weglassen und für den Benutzer kein Gesicht gespeichert ist, schlägt die Sitzungserstellung mit `400` und der Meldung `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.` fehl. Wenn Sie auch `vendor_data` weglassen, fordert die `400`-Meldung Sie dazu auf, ein `portrait_image` oder `vendor_data` mit einem gespeicherten Gesicht zu senden.**2. Live-Fotoerfassung**Während des Authentifizierungsprozesses:| Prüfung | Beschreibung |
| - | - |
| **Liveness-Prüfung** | Verhindert Spoofing mittels Passive Liveness oder 3D Action & Flash |
| **Bildqualität** | Das System bewertet Beleuchtung, Positionierung und Schärfe |
| **Anleitung für Wiederholungsversuche** | Bilder von schlechter Qualität werden mit Hinweisen zur Verbesserung abgelehnt |
| **Echtzeit-Feedback** | Der Benutzer erhält Positionierungshilfen für eine optimale Aufnahme |**3. Verifizierung und Ergebnisverarbeitung**Das System verarbeitet die Verifizierung basierend auf Ihrer Workflow-Konfiguration:> [accordion] Nur-Liveness-Modus
>
> Wenn **Face Match im Workflow deaktiviert** ist, bestätigt das System nur die Liveness des Benutzers; es ist kein Referenzgesicht erforderlich und `portrait_image` wird nicht benötigt. Eine erfolgreiche Prüfung führt zu einer **genehmigten** Authentifizierung, was für eine einfache Anwesenheitsverifizierung nützlich ist.> [accordion] Modus Liveness + Face Match
>
> Wenn **Face Match im Workflow aktiviert** ist (Referenzgesicht aus `portrait_image` oder dem gespeicherten Gesicht des Benutzers):
>
> 1. Das System führt zuerst die **Liveness-Prüfung** durch
> 2. Wenn die Liveness-Prüfung bestanden wurde, vergleicht es das neue Selfie mit dem Referenzgesicht
> 3. Es wird ein **Ähnlichkeitswert (0–100%)** generiert
> 4. Wert über Ihrem konfigurierten Schwellenwert → **Genehmigt**
> 5. Wert unter dem Schwellenwert → **Abgelehnt**Die Ergebnisse sind über die **API-Antwort**, die **Business-Konsole** und **Webhooks** verfügbar.


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