Biometric verification (v2)

BIOMETRIC_VERIFICATION:v2 is in preview

BIOMETRIC_VERIFICATION:v2 is in preview. The Verification data block implementation is not yet finalised and may change before general availability. Use BIOMETRIC_VERIFICATION:v1 for production flows.

Authenticates identity using facial recognition

Used when strong, real‑time identity confirmation is required. The user completes a quick face scan, and the system ensures they are a real person and match the enrolled face, helping prevent impersonation, spoofing, and deepfakes.

---

Key features

• Liveness detection: Confirms the user is physically present and not a spoof or replay attack.
• Face comparison: Matches the live capture against the enrolled biometric template.
• Evidence preservation: On success, the Keyless transaction JWT is stored in the vault and referenced in the Verification data block for audit purposes.

This step requires previous enrolment via the Biometric Enrolment step and uses the captured biometric data to authenticate the user.

---

Configuration

Option	Type	Required	Default	Description
provider	"KEYLESS"	No	—	Biometric verification provider. Currently KEYLESS is the only supported value and is used regardless of this field.
enableRetry	boolean	No	false	When enabled, adds a retry route for user cancellation.

Example configuration

{
  "enableRetry": true
}

---

Input data blocks

Data block	Required	Description
UserReference	Yes	Contains the unique subject identifier (subjectId) necessary to identify the user in the Keyless system.

---

Routes

Route	Description
verified	Biometric authentication succeeded. The user has been verified.
rejected	Biometric authentication failed due to a biometric mismatch or technical error during the check.
retry	Available when enableRetry: true. User cancelled and can retry.

info

User cancellation triggers the retry route when enableRetry: true. When enableRetry is not set, cancellation causes the session to be aborted (no named route). rejected covers all known failure outcomes — biometric mismatch and known technical error codes alike. An unexpected system failure (e.g. service unavailable) surfaces as a session error outside any named route.

---

Output data blocks

Route	Data blocks produced	Notes
verified	Verification	Authentication succeeded. Contains verification methods and evidence (JWT stored in vault). Provider, trust framework, and assurance level are not populated (null).
rejected	Verification	Authentication failed. Status is rejected, aborted, or error depending on the failure reason. For a face mismatch, methods array contains a single faceComparison: failed check; for other rejection reasons, checks is an empty array. No evidence or trust framework populated.
retry	Verification	User cancelled and can retry. Available when enableRetry: true.

Verification data block

The Verification data block produced by BIOMETRIC_VERIFICATION:v2 describes the outcome of the biometric authentication.

Field	Type	Description
status	string	Verification status. One of: verified, rejected, aborted, error.
provider	string | null	Always null (not currently populated).
trustFramework	string | null	Always null (not currently populated).
assuranceLevel	string | null	Always null (not currently populated).
verifiedAt	string	ISO 8601 timestamp at which the process completed.
verificationProcessId	string | null	Keyless transaction ID.
terminationReason	object | null	Present when the process ended before completion. Contains code (string) and message (string | null). null on success.
methods	array	Always contains one entry of type biometric. See below.

methods[].biometric

Field	Type	Description
type	string	Always "biometric".
checks	array	Techniques applied. On success: empty array (verification proven by evidence JWT). On face mismatch rejection: [{ technique: "faceComparison", outcome: "failed" }]. On other rejections, aborted, or error: empty array.
evidence	array	On success: [{ type: "transactionJwt", ref: { "$ref": "vault", "$id": "..." } }] — Keyless JWT stored as a binary vault entry. On failure: empty array.

Example payloads

Verification — verified

{
  "dataBlockId": "58d1fbce-8f9a-4e2a-bff9-54bdf124696c",
  "type": "Verification",
  "status": "verified",
  "terminationReason": null,
  "methods": [
    {
      "type": "biometric",
      "checks": [],
      "evidence": [
        {
          "type": "transactionJwt",
          "ref": {
            "$ref": "vault",
            "$id": "5e8de376-caa3-40a8-a998-8627a7d4d009"
          }
        }
      ]
    }
  ],
  "provider": null,
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:00:01.000Z",
  "verificationProcessId": "txn-keyless-abc123"
}

Verification — rejected (face mismatch)

{
  "dataBlockId": "41a39afc-3906-4c2d-84f1-fa27ff2a2c30",
  "type": "Verification",
  "status": "rejected",
  "terminationReason": {
    "code": "FACE_MISMATCH",
    "message": "Biometric comparison failed: faces did not match."
  },
  "methods": [
    {
      "type": "biometric",
      "checks": [{ "technique": "faceComparison", "outcome": "failed" }],
      "evidence": []
    }
  ],
  "provider": null,
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:01:15.000Z",
  "verificationProcessId": "txn-keyless-def456"
}

---