> ## 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과 동일한 신경망 아키텍처 사용
- 계정 탈취 시도 방지
- 스푸핑을 방지하기 위한 라이브니스 감지 포함#### 연동 유연성- 웹 기반으로 제공
- 일치 임계값 구성 가능
- 보안 강화를 위한 선택적 기기 및 IP 분석## 작동 방식**1. 세션 생성****얼굴 대조**가 포함된 워크플로에 대해 생체 인증 세션을 생성할 때, Didit은 라이브 셀피와 비교할 기준 얼굴이 필요합니다.
두 가지 옵션이 있습니다:- 자체 데이터베이스에서 Base64 형식의 **`portrait_image` 전송**(최대 2MB). 제공되는 경우 항상 우선 적용됩니다.
- **`portrait_image`를 생략**하고 사용자의 `vendor_data`를 전달. Didit은 해당 사용자에 대해 이미 저장된 얼굴을 다음 순서로 확인하여 자동으로 재사용합니다:
  1. **승인된 라이브니스 검사** 중에 캡처된 얼굴
  2. 승인된 신분증 인증의 **전자여권 칩 사진**
  3. 승인된 신분증 인증의 **신분증에서 잘라낸 인물 사진**
  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. 인증 및 결과 처리**시스템은 워크플로 구성에 따라 인증을 처리합니다:> [accordion] 라이브니스 전용 모드
>
> 워크플로에서 **얼굴 대조가 비활성화**된 경우, 시스템은 사용자의 라이브니스만 확인합니다. 기준 얼굴이 필요하지 않으며 `portrait_image`도 요구되지 않습니다. 검사가 성공하면 **승인됨** 상태의 인증 결과가 생성되며, 단순한 실재 여부 확인에 유용합니다.> [accordion] 라이브니스 + 얼굴 대조 모드
>
> 워크플로에서 **얼굴 대조가 활성화**된 경우(`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.