取代短信 2FA。
刷脸，一秒搞定。

# Didit Biometric Authentication — integrate in 5 minutes

You are integrating Didit's Biometric Authentication module into <my_stack>.
This is a returning-user passwordless re-verification flow — a drop-in
replacement for SMS or email 2FA at high-value actions (large transfers,
password reset, large withdrawals, sensitive setting changes). It is NOT
the first-time KYC sign-up flow — for that, see Didit Liveness at
docs.didit.me/core-technology/liveness/overview.

Every URL, header, and enum value below is canonical — do not paraphrase
or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Create the biometric_authentication workflow (one time)
Biometric Authentication is a workflow_type, not a feature flag. Create
the workflow once, reuse the workflow_id for every authentication.

POST https://verification.didit.me/v3/workflows/
Header: x-api-key: <your-api-key>
Body:
  - workflow_label   (your label, e.g. "step-up-2fa")
  - workflow_type    "biometric_authentication"  (snake_case enum)
  - features         the array
                       [{ feature: "LIVENESS" }]                    (liveness-only mode)
                     OR
                       [{ feature: "LIVENESS" }, { feature: "FACE_MATCH" }]  (face-match mode)
  - liveness_method  "PASSIVE" | "FLASHING" | "ACTIVE_3D"   (PASSIVE recommended for low-friction step-up)

Store the returned workflow_id — you will reuse it on every auth.

## 3. Authenticate a returning user

POST https://verification.didit.me/v3/session/
Header: x-api-key: <your-api-key>
Header: Content-Type: application/json
Body:
  - workflow_id     (from step 2)
  - vendor_data     (your own user id, e.g. "user-42")
  - callback        (optional URL we redirect the user to after capture)
  - metadata        (optional JSON, surfaced back on the webhook)
  - portrait_image  (Base64 JPEG, REQUIRED when the workflow has FACE_MATCH;
                     OMIT for liveness-only mode)

The portrait_image is the stored reference photo from the user's original
KYC verification (you already have it as id_verification.portrait_image in
the original session response). Send it as a Base64-encoded JPEG, max 1 MB.

Response: session_url — redirect the user to it. Didit hosts the capture
(camera, motion prompts, low-light fallback, accessibility) and posts the
verdict back via webhook.

## 4. Webhooks
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.declined",
                                  "session.review_started"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 5. Reading the report
The webhook payload (and the GET /v3/session/{id}/decision/ response)
returns the combined biometric_authentication shape:

  status               "Approved" | "Declined" | "Not Finished"
  workflow_id          string
  session_id           uuid
  session_number       integer
  vendor_data          your user id
  liveness:
    status             "Approved" | "Declined" | "Not Finished"
    method             "PASSIVE" | "FLASHING" | "ACTIVE_3D"
    score              number 0-100
    reference_image    signed URL to the captured selfie (expires in 1 hour)
    video_url          signed URL (FLASHING and ACTIVE_3D only, expires in 1 hour)
    warnings           array
  face_match:                     (only present in face-match mode)
    status             "Approved" | "Declined" | "Not Finished"
    score              number 0-100 (similarity %)
    source_image       signed URL to the captured selfie
    target_image       signed URL to the supplied portrait_image
    warnings           array

Overall status is "Approved" only when liveness.status == "Approved" AND
(face_match is absent OR face_match.status == "Approved").

Auto-decline triggers (always enforced by Didit, not configurable):
  FACE_IN_BLOCKLIST, NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, NO_REFERENCE_IMAGE

Configurable risks (action per workflow — Decline, Review, or Approve):
  LOW_LIVENESS_SCORE, LOW_FACE_MATCH_SIMILARITY

## 6. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- workflow_type is snake_case: biometric_authentication.
- Feature enums inside the workflow are UPPERCASE: LIVENESS, FACE_MATCH.
- Liveness 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).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Not Finished" (title-cased, space-separated).
- portrait_image is Base64 JPEG, max 1 MB, required only in face-match mode.

## 7. Pricing reference (public)
- Biometric Authentication: $0.10 per authentication (passwordless re-auth).
- 500 free authentications every month, forever, on every account.
- For the original sign-up KYC, see https://didit.me/pricing (full KYC
  bundle is $0.33 per onboarded user, which includes Liveness + Face Match +
  ID Verification + Device & IP Analysis).

## 8. When to use this versus Liveness directly
- First-time KYC sign-up: use Liveness (the feature) inside an ID
  Verification workflow. See docs.didit.me/core-technology/liveness/overview.
- Step-up at sensitive actions (transfer, password reset, large
  withdrawal): use this Biometric Authentication workflow.
- High-volume passive monitoring (any login): use this workflow with
  liveness-only mode (no portrait_image) — fastest, lowest friction.

## 9. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test images: deterministic synthetic faces returned in sandbox
  (Approved by default; trigger Declined by sending the canonical "spoof"
  test image).
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/biometric-auth/overview