Authentication (v2)
BIOMETRIC_VERIFICATION:v2 is in preview. The Verification data block implementation is not yet finalized 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
Verificationdata block for audit purposes.
This step requires previous enrollment via the Biometric Enrollment step and uses the captured biometric data to authenticate the user.
Configuration
| Attribute | 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. |
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. |
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 | Description |
|---|---|---|
| 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 structure
The Verification data block contains:
- status:
verified|rejected|fraudDetected|canceled|aborted|error - methods[0].type:
biometric - methods[0].checks: Array of performed checks. Possible techniques:
livenessDetection,faceComparison, each with outcomepassed|failed:- On success: empty array — verification is proven solely by the
evidencefield (transactionJwt), not by individual check outcomes - On rejection due to face mismatch: single check,
faceComparison: failed - On other rejections, aborted, or error: empty array
- On success: empty array — verification is proven solely by the
- methods[0].evidence: On success:
[{ type: 'transactionJwt', ref: { $ref: 'vault', $id: '...' } }]— JWT stored as binary vault entry; on failure: empty array - terminationReason: Object with
code(string) andmessage(string | null). Present when the process ended before completion (aborted, rejected, or error);nullon success. - provider:
null(not currently populated) - trustFramework:
null(not currently populated) - assuranceLevel:
null(not currently populated) - verifiedAt: ISO 8601 timestamp
- verificationProcessId: Keyless transaction ID