> ## 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 palavra-passe

> Autentique utilizadores com prova de vida e correspondência facial na Didit. Sem documentos, em menos de 2 segundos. Pague por chamada: $0.10.

A solução de Autenticação biométrica da Didit proporciona uma experiência de verificação simplificada para utilizadores que regressam. Este fluxo pode ser configurado para realizar uma verificação apenas de prova de vida para verificação simples de presença, ou combinar prova de vida com reconhecimento facial para uma confirmação de identidade mais robusta face a um retrato guardado. Esta flexibilidade cria uma experiência sem atritos, mantendo elevados padrões de segurança.

Prompt de integração da Autenticação biométrica
        Copiar o prompt para a área de transferência



      
      

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



      
      

Colar em

## Principais funcionalidades#### Reverificação rápida- Sem necessidade de digitalização de documentos
- Verificação concluída em segundos
- Reduz o atrito e o abandono do utilizador#### Segurança avançada- Utiliza a mesma arquitetura de redes neuronais que a Correspondência facial 1:1
- Previne tentativas de apropriação de contas
- Inclui prova de vida para prevenir spoofing#### Flexibilidade de integração- Disponível via web
- Limiares de correspondência configuráveis
- Análise de dispositivo e IP opcional para maior segurança## Como funciona**1. Criação da sessão**Quando cria uma sessão de autenticação biométrica para um fluxo com **correspondência facial**, a Didit necessita de uma face de referência para comparar com a selfie em tempo real.
Tem duas opções:- **Enviar `portrait_image`** em Base64 (máx. 2MB) a partir da sua própria base de dados. Prevalece sempre quando fornecida.
- **Omitir `portrait_image`** e transmitir o `vendor_data` do utilizador. A Didit reutiliza automaticamente a face já guardada para esse utilizador, resolvida pela seguinte ordem:
  1. Face capturada durante uma **verificação de prova de vida aprovada**
  2. **Fotografia do chip do ePassport** de uma verificação de identidade aprovada
  3. **Retrato recortado do documento de identificação** de uma verificação de identidade aprovada
  4. **Face de perfil registada manualmente** (Users API ou carregamento na Consola)```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]
>
> Apenas as faces de sessões **aprovadas** (ou faces que tenha registado pessoalmente) são reutilizadas. Se omitir `portrait_image` e o utilizador não tiver uma face guardada, 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 omitir também `vendor_data`, a mensagem `400` solicita o envio de uma `portrait_image` ou de um `vendor_data` com uma face guardada.**2. Captura de fotografia em tempo real**Durante o processo de autenticação:| Verificação | Descrição |
| - | - |
| **Verificação de prova de vida** | Previne spoofing através de Prova de Vida Passiva ou Ação 3D e Flash |
| **Qualidade da imagem** | O sistema avalia a iluminação, o posicionamento e a nitidez |
| **Orientação para nova tentativa** | As imagens de fraca qualidade são rejeitadas com instruções de melhoria |
| **Feedback em tempo real** | O utilizador visualiza guias de posicionamento para uma captura ideal |**3. Processamento da verificação e dos resultados**O sistema processa a verificação com base na configuração do seu fluxo:> [accordion] Modo apenas de prova de vida
>
> Se a **Correspondência facial estiver desativada** no fluxo, o sistema apenas confirma a prova de vida do utilizador; não é necessária nenhuma face de referência e `portrait_image` não é obrigatória. Uma verificação bem-sucedida resulta numa autenticação **aprovada**, útil para uma simples verificação de presença.> [accordion] Modo de prova de vida + Correspondência facial
>
> Se a **Correspondência facial estiver ativada** no fluxo (face de referência a partir de `portrait_image` ou da face guardada do utilizador):
>
> 1. O sistema realiza primeiro a **verificação de prova de vida**
> 2. Se a prova de vida for bem-sucedida, compara a nova selfie com a face de referência
> 3. É gerada uma **pontuação de semelhança (0–100%)**
> 4. Pontuação acima do limiar configurado → **Aprovado**
> 5. Pontuação abaixo do limiar → **Recusado**Os resultados estão disponíveis através da **resposta da API**, da **Consola Empresarial** e de **webhooks**.


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