Biometric verification (v2)

Preview / Alpha

This version of this step type is in preview / alpha. The functionality and subsequently the documentation can still change. The stable / GA version of this step is Biometric verification (v1)

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 (v1) step and uses the captured biometric data to authenticate the user.

---

Configuration

Option	Type	Required	Default	Description
provider	string	No	—	Biometric verification provider. Currently KEYLESS is the only supported value and is used regardless of this field. Accepted values: KEYLESS.
enableRetry	boolean	No	false	When true, adds a retry output route that can be used to handle user cancellations.

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. Reuse the same subjectId that was used for the enrollment.

Reuse of existing subjectId

For the Biometric Authentication to be successful, the same subjectId that was used for Biometric Enrolment needs to be used.

---

Routes

Route	Description
verified	Biometric authentication succeeded. The user has been verified. The Verification data block contains the authentication methods and evidence (JWT stored in the vault); the provider, trust framework, and assurance level are not populated (null).
rejected	Biometric authentication failed due to a biometric mismatch or technical error during the check. The status is rejected, aborted, or error depending on the failure reason: for a face mismatch, the methods array contains a single faceComparison: failed check; for other rejection reasons, checks is an empty array. No evidence or trust framework is populated.
retry	Available only when enableRetry is 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
verified	Verification
rejected	Verification
retry	Verification Available only when enableRetry is true.

Verification data block

The Verification data block produced by this step 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

{
  "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)

{
  "status": "rejected",
  "terminationReason": {
    "code": "SERVER_FACE_DOES_NOT_MATCH",
    "message": null
  },
  "methods": [
    {
      "type": "biometric",
      "checks": [
        {
          "technique": "faceComparison",
          "outcome": "failed",
          "issues": []
        }
      ],
      "evidence": []
    }
  ],
  "provider": null,
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:01:15.000Z",
  "verificationProcessId": "txn-keyless-def456"
}

---