> ## 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 de autenticação biométrica: KYC sem senha

> A Didit autentica usuários recorrentes com prova de vida e correspondência facial, sem documentos e em menos de 2 segundos. $0.10 por chamada.

A solução de Autenticação biométrica da Didit oferece uma experiência de verificação simplificada para usuários recorrentes. Esse fluxo pode ser configurado para fazer apenas uma verificação de prova de vida, para uma simples confirmação de presença, ou combinar a prova de vida com reconhecimento facial para uma confirmação de identidade mais forte contra um retrato armazenado. Essa flexibilidade cria uma experiência sem atrito e mantém altos padrões de segurança.

Prompt de integração da Autenticação biométrica
        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

## Principais recursos#### Reverificação rápida- Não exige escaneamento de documento
- Verificação concluída em segundos
- Reduz o atrito e o abandono do usuário#### Segurança avançada- Usa a mesma arquitetura de rede neural da Correspondência facial 1:1
- Impede tentativas de tomada de conta
- Inclui detecção de prova de vida para evitar falsificações#### Flexibilidade de integração- Disponível na web
- Limites de correspondência configuráveis
- Análise de dispositivo e IP opcional para mais segurança## Como funciona**1. Criação da sessão**Quando você cria uma sessão de autenticação biométrica para um fluxo de verificação (workflow) com **correspondência facial**, a Didit precisa de um rosto de referência para comparar com a selfie ao vivo.
Você tem duas opções:- **Envie `portrait_image`** em Base64 (máx. 2MB) a partir do seu próprio banco de dados. Ela sempre tem precedência quando informada.
- **Omita `portrait_image`** e informe o `vendor_data` do usuário. A Didit reutiliza automaticamente o rosto já armazenado para esse usuário, resolvido nesta ordem:
  1. Rosto capturado durante uma **prova de vida aprovada**
  2. **Foto do chip do ePassport** de uma verificação de identidade aprovada
  3. **Retrato recortado do documento de identidade** de uma verificação de identidade aprovada
  4. **Rosto de perfil cadastrado manualmente** (API de Usuários ou upload pelo 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]
>
> Só são reutilizados rostos de sessões **aprovadas** (ou rostos que você mesmo cadastrou). Se você omitir `portrait_image` e o usuário não tiver rosto armazenado, a criação da sessão falha com `400` e a mensagem `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.` Se você também omitir `vendor_data`, a mensagem do `400` pede que você envie um `portrait_image` ou um `vendor_data` com rosto armazenado.**2. Captura da foto ao vivo**Durante o processo de autenticação:| Verificação | Descrição |
| - | - |
| **Verificação de prova de vida** | Impede falsificações com Prova de vida passiva ou Ação 3D e Flash |
| **Qualidade da imagem** | O sistema avalia iluminação, posicionamento e nitidez |
| **Orientação para nova tentativa** | Imagens de baixa qualidade são rejeitadas com instruções de melhoria |
| **Feedback em tempo real** | O usuário vê guias de posicionamento para uma captura ideal |**3. Verificação e processamento do resultado**O sistema processa a verificação de acordo com a configuração do seu fluxo:> **Modo somente prova de vida**
>
> Se a **Correspondência facial estiver desativada** no fluxo, o sistema apenas confirma a prova de vida do usuário; não é necessário rosto de referência e `portrait_image` não é obrigatório. Uma verificação bem-sucedida resulta em uma autenticação **aprovada**, útil para uma simples verificação de presença.> **Modo prova de vida + correspondência facial**
>
> Se a **Correspondência facial estiver ativada** no fluxo (rosto de referência vindo de `portrait_image` ou do rosto armazenado do usuário):
>
> 1. O sistema executa primeiro a **verificação de prova de vida**
> 2. Se a prova de vida passar, compara a nova selfie com o rosto de referência
> 3. É gerada uma **pontuação de similaridade (0–100%)**
> 4. Pontuação acima do limite configurado → **Aprovada**
> 5. Pontuação abaixo do limite → **Recusada**Os resultados estão disponíveis pela **resposta da API**, pelo **Business Console** e por **webhooks**.


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