Sign the user back in. With one selfie.

You are integrating Didit&apos;s selfie-only re-authentication into <my_stack>. Replace password, SMS one-time-password, or magic-link on returning-user surfaces with a sub-2-second face match against the enrolled portrait. Phishing-resistant, no carrier dependency, no SIM-swap surface, no email-delivery delay.

  1. Enrol the user&apos;s portrait ONCE at sign-up (standard Know Your Customer (KYC) session).
  2. On every returning-user sign-in, open a re-auth session that runs Passive Liveness + Face Match 1:1 against the stored portrait. ~2 seconds end-to-end.

Pricing (public):
  - Selfie re-auth: $0.10 per authentication (Sessions API)
  - First 500 verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with Hash-based Message Authentication Code (HMAC) SHA-256 verification using the X-Signature-V2 header.
  - The user has previously enrolled via a Didit KYC session (the portrait captured during the liveness step is stored automatically, bound to vendor_data).
  - A workflow_id from the Workflow Builder. The workflow MUST contain LIVENESS, and the session is opened with workflow_type = "biometric_authentication".

STEP 1 — Open a re-auth session

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<your biometric_authentication workflow>",
      "workflow_type": "biometric_authentication",
      "vendor_data": "<the same user id used at enrolment>",
      "callback": "https://<your-app>/reauth/callback",
      "metadata": {
        "purpose": "returning_user_signin",
        "device_id": "<optional, your device fingerprint>",
        "from_ip": "<optional, the request IP>"
      },
      "portrait_image": "<base64 JPEG of the user's enrolment selfie, ≤ 1 MB — REQUIRED when the workflow has FACE_MATCH active; OMIT for liveness-only mode>"
    }

  Response: 201 Created with the hosted session_url. Redirect the user. The hosted UI opens the front camera, captures one passive frame, runs Liveness + Face Match 1:1 against the user&apos;s enrolled portrait, returns the verdict in sub-2-seconds.

STEP 2 — Read the signed verdict on the webhook

  Body (excerpted for a passing re-auth):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "liveness": {
        "status": "Approved",
        "method": "PASSIVE",
        "score": 96
      },
      "face": {
        "status": "Approved",
        "similarity_score": 0.96
      }
    }

  Verify X-Signature-V2 BEFORE trusting the body — HMAC SHA-256 of the raw bytes with your webhook secret.

  Session status enum (exact case): Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned.

STEP 3 — Branch your sign-in logic on the verdict

  Approved      → mint your session token, sign the user in.
  Declined      → block sign-in; fall back to a higher-friction recovery (support contact / full KYC re-do).
  In Review     → hold; route to your operations queue.
  Not Finished  → user abandoned the capture; safe to re-prompt or fall back to a backup factor.

STEP 4 — Adaptive step-up (recommended)

  Pair the selfie with Device & IP Analysis (bundled into the 200+ fraud-signal stack at no extra cost). Adaptive rules to consider:

    Known device + known Internet Protocol (IP)  → skip the selfie, mint a session token.
    Known device + new IP                         → run the selfie (passive).
    New device + new IP                           → run the selfie (passive).
    Tor / Virtual Private Network (VPN) exit +
      new device                                  → escalate to ACTIVE_3D method (motion challenge).

  Implement the branching in your application or in the Workflow Builder via per-session overrides.

CONSTRAINTS
  - Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
  - Feature enum is UPPERCASE: LIVENESS, FACE_MATCH, IP_ANALYSIS, ID_VERIFICATION, AML, AGE_ESTIMATION.
  - Method enum is UPPERCASE: PASSIVE, FLASHING, ACTIVE_3D.
  - Auth header is x-api-key (lowercase, hyphenated).
  - Webhook signature header is X-Signature-V2 (NOT X-Signature).
  - Status casing matches exactly: Approved, Declined, In Review, Expired, Not Finished, Resubmitted, Kyc Expired, Abandoned.
  - The face template is irreversible (a one-way hash). The user can request deletion via the standard data-subject-request path.

PRO TIPS
  - Bind a Reusable Credential to each enrolled user. The next Didit-powered surface that needs the same gate consumes the credential at zero cost.
  - Keep a fallback factor (password, magic link, support recovery) for users who cannot complete the selfie — accessibility, device camera failure, religious head covering, etc.

Read the docs:
  - https://docs.didit.me/core-technology/biometric-auth/overview
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/integration/webhooks

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 verifications free every month, no credit card.