> ## 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 的生物识别认证结合活体检测与人脸比对，为老用户提供无需证件的无密码认证，不到 2 秒完成，按次调用 $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 相同的神经网络架构
- 防止账户劫持攻击
- 包含活体检测以防止欺骗攻击#### 灵活集成- 支持 Web 端
- 可配置匹配阈值
- 可选设备与 IP 分析以提升安全性## 工作原理**1. 创建会话**当您为包含**人脸比对**的工作流创建生物识别认证会话时，Didit 需要一张参考人脸来与实时自拍照进行比对。
您有两种选择：- **从您自己的数据库发送 Base64 格式的 `portrait_image`**（最大 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.