> ## 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秒未満のパスワードレス認証を実現し、料金は1回あたり$0.10です。

Diditの生体認証は、再訪ユーザー向けに合理化された認証体験を提供します。ワークフローは、単純な本人の存在確認のためにライブネスのみのチェックを行う設定にも、保存済みの顔写真と照合して本人をより強く確認するためにライブネスと顔認識を組み合わせる設定にもできます。この柔軟性により、高いセキュリティ水準を保ちながら、手間のない体験を実現します。

生体認証の連携プロンプト
        Copy prompt to clipboard



      
      

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



      
      

Paste into

## 主な機能#### 高速な再認証- 書類のスキャンは不要
- 数秒で認証を完了
- ユーザーの手間と離脱を減らす#### 高度なセキュリティ- 顔照合1:1と同じニューラルネットワークアーキテクチャを使用
- アカウント乗っ取りの試みを防止
- ライブネス検知により、なりすましを防止#### 柔軟な連携- Webベースで利用可能
- 設定可能な照合しきい値
- 任意のデバイス・IP分析でセキュリティを強化## 仕組み**1. セッションの作成****顔照合**を有効にしたワークフローで生体認証セッションを作成する場合、Diditはライブの自撮りと比較するための基準となる顔を必要とします。
次の2つの方法があります。- ご自身のデータベースから、Base64形式(最大2MB)の\*\*`portrait_image`を送信\*\*します。指定した場合は常にこちらが優先されます。
- **`portrait_image`を省略**し、ユーザーの`vendor_data`を渡します。Diditは、そのユーザーについてすでに保存されている顔を、次の順序で解決して自動的に再利用します。
  1. **承認済みのライブネスチェック**で撮影された顔
  2. 承認済みの本人確認の**ePassportチップの写真**
  3. 承認済みの本人確認の**ID書類から切り出した顔写真**
  4. **手動で登録されたプロファイルの顔**(Users APIまたはコンソールからのアップロード)```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. ライブ写真の撮影**認証プロセスでは、次のことが行われます。| チェック | 説明 |
| - | - |
| **ライブネス検証** | パッシブライブネスまたは3Dアクション&フラッシュで、なりすましを防止します |
| **画像の品質** | 照明、位置、鮮明さをシステムが評価します |
| **再撮影のガイダンス** | 品質の低い画像は、改善方法の案内とともに却下されます |
| **リアルタイムのフィードバック** | 最適な撮影のための位置ガイドが表示されます |**3. 検証と結果の処理**システムは、ワークフローの設定に基づいて検証を処理します。> **ライブネスのみのモード**
>
> ワークフローで**顔照合が無効**の場合、システムはユーザーのライブネスのみを確認します。基準となる顔は不要で、`portrait_image`も必要ありません。チェックに成功すると認証は**承認済み**となり、単純な本人の存在確認に便利です。> **ライブネス + 顔照合モード**
>
> ワークフローで**顔照合が有効**の場合(基準となる顔は`portrait_image`またはユーザーの保存済みの顔):
>
> 1. システムはまず**ライブネスチェック**を実行します
> 2. ライブネスに合格したら、新しい自撮りを基準となる顔と比較します
> 3. \*\*類似度スコア(0–100%)\*\*が生成されます
> 4. 設定したしきい値を上回るスコア → **承認済み**
> 5. しきい値を下回るスコア → **拒否**結果は、**APIレスポンス**、**ビジネスコンソール**、**Webhook**で確認できます。


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