> ## 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 требуется эталонное изображение лица для сопоставления с селфи в реальном времени.
У вас есть два варианта:- **Передать `portrait_image`** в Base64 (до 2MB) из собственной базы данных. При наличии этот параметр всегда имеет приоритет.
- **Не передавать `portrait_image`** и указать `vendor_data` пользователя. Didit автоматически повторно использует лицо, уже сохраненное для этого пользователя, выбирая его в следующем порядке приоритета:
  1. Лицо, полученное во время **одобренной проверки живости**
  2. **Фото с чипа ePassport** из одобренной верификации личности
  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. Съемка фото в реальном времени**В процессе аутентификации:| Проверка | Описание |
| - | - |
| **Проверка живости** | Предотвращает спуфинг с помощью пассивной проверки живости (Passive Liveness) или 3D Action & Flash |
| **Качество изображения** | Система оценивает освещение, положение лица и четкость |
| **Подсказки при повторных попытках** | Некачественные снимки отклоняются с рекомендациями по улучшению |
| **Обратная связь в реальном времени** | Пользователь видит направляющие рамки для оптимального кадра |**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.