> ## 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: تحقق KYC بدون كلمة مرور

> تصادق Didit المستخدمين العائدين بكشف الحيوية ومطابقة الوجه دون مستندات أو كلمات مرور، في أقل من ثانيتين، بسعر $0.10 لكل استدعاء.

يوفر حل المصادقة البيومترية من Didit تجربة تحقق مبسطة للمستخدمين العائدين. يمكن تكوين سير العمل هذا لإجراء فحص للحيوية فقط للتحقق البسيط من الوجود، أو الجمع بين كشف الحيوية والتعرف على الوجه لتأكيد الهوية بشكل أقوى من خلال مقارنتها بصورة شخصية مخزنة. تخلق هذه المرونة تجربة سلسة مع الحفاظ على معايير أمان عالية.

موجه تكامل المصادقة البيومترية
        نسخ الموجّه إلى الحافظة



      
      

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



      
      

الصق في

## الميزات الرئيسية#### إعادة التحقق السريعة- لا يلزم مسح المستندات ضوئياً
- إتمام التحقق في ثوانٍ
- يقلل من الاحتكاك والتخلّي#### أمان متقدم- يستخدم نفس بنية الشبكة العصبية المستخدمة في مطابقة الوجه 1:1
- يمنع محاولات الاستيلاء على الحساب
- يتضمن كشف الحيوية لمنع الانتحال#### مرونة التكامل- متاح عبر الويب
- حدود تطابق قابلة للتكوين
- تحليل الجهاز وعنوان IP اختياري لتعزيز الأمان## كيفية العمل**1. إنشاء الجلسة**عند إنشاء جلسة مصادقة بيومترية لسير عمل يتضمن **مطابقة الوجه**، يحتاج Didit إلى وجه مرجعي لمقارنة صورة السيلفي المباشرة به.
لديك خياران:- **إرسال `portrait_image`** بتنسيق Base64 (بحد أقصى 2MB) من قاعدة بياناتك الخاصة. وتكون له الأولوية دائماً عند تقديمه.
- **عدم إرسال `portrait_image`** وتمرير `vendor_data` الخاص بالمستخدم. يعيد Didit تلقائياً استخدام الوجه المخزن بالفعل لهذا المستخدم، ويتم تحديده وفقاً لهذا الترتيب:
  1. الوجه الذي تم التقاطه أثناء **فحص حيوية مقبول**
  2. **صورة شريحة جواز السفر الإلكتروني** من عملية تحقق من الهوية مقبولة
  3. **الصورة الشخصية المقتصّة من مستند الهوية** من عملية تحقق من الهوية مقبولة
  4. **وجه الملف الشخصي المسجل يدوياً** (عبر Users API أو الرفع من 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]
>
> لا يُعاد استخدام سوى الوجوه المأخوذة من الجلسات **المقبولة** (أو الوجوه التي قمت بتسجيلها بنفسك). إذا لم ترسل `portrait_image` ولم يكن لدى المستخدم وجه مخزن، فسيفشل إنشاء الجلسة بالرمز `400` والرسالة `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.`. وإذا لم ترسل `vendor_data` أيضاً، فستطلب منك الرسالة `400` إرسال `portrait_image` أو `vendor_data` يحتوي على وجه مخزن.**2. التقاط الصورة المباشرة**أثناء عملية المصادقة:| الفحص | الوصف |
| - | - |
| **التحقق من الحيوية** | يمنع الانتحال باستخدام Passive Liveness أو 3D Action & Flash |
| **جودة الصورة** | يقيّم النظام الإضاءة، والموضع، والوضوح |
| **إرشادات إعادة المحاولة** | تُرفض الصور منخفضة الجودة مع تقديم تعليمات للتحسين |
| **ملاحظات فورية** | يرى المستخدم إرشادات لضبط الموضع لالتقاط الصورة على النحو الأمثل |**3. التحقق ومعالجة النتائج**يعالج النظام عملية التحقق بناءً على تكوين سير العمل لديك:> [accordion] وضع كشف الحيوية فقط
>
> إذا تم **تعطيل مطابقة الوجه** في سير العمل، فإن النظام يؤكد حيوية المستخدم فقط؛ ولا يلزم وجود وجه مرجعي كما أن `portrait_image` غير مطلوب. ينتج عن الفحص الناجح مصادقة **مقبولة**، وهو أمر مفيد للتحقق البسيط من الوجود.> [accordion] وضع كشف الحيوية + مطابقة الوجه
>
> إذا تم **تمكين مطابقة الوجه** في سير العمل (الوجه المرجعي من `portrait_image` أو الوجه المخزن للمستخدم):
>
> 1. يجري النظام **فحص الحيوية** أولاً
> 2. إذا تم اجتياز كشف الحيوية، فإنه يقارن صورة السيلفي الجديدة بالوجه المرجعي
> 3. يتم إنشاء **درجة تشابه (0–100%)**
> 4. درجة أعلى من الحد الذي قمت بتكوينه ← **مقبولة**
> 5. درجة أقل من الحد ← **مرفوضة**تتوفر النتائج عبر **استجابة API**، و**Business Console**، و**webhook**.


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