Authentication (v2)

Preview

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 Verification data 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	Description
provider	string	No	The biometric provider to use. Accepted value: keyless. When omitted, the provider is resolved from the Third Party configuration defined at infrastructure level.

---

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.

note

User cancellation causes the session to be aborted (no named route). A technical failure in the verification process surfaces as a session error. rejected applies specifically to a completed check where the result was negative.

---

Output data blocks

Route	Data blocks produced	Description
verified	Verification	Authentication succeeded. Contains verification methods, evidence (JWT stored in vault), provider (keyless), trust framework (io.idnow.biometric), and assurance level (substantial).
rejected	Verification	Authentication failed. Status is rejected; methods array contains checks with failed outcome; no evidence or trust framework populated.

---

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:
  • livenessDetection: liveness check result (passed | failed)
  • faceComparison: face comparison against enrolled template (passed | failed)
  • On success: both checks show passed
  • On rejection: both checks show failed
  • On aborted/error: empty array
• methods[0].evidence: On success: [{ type: 'transactionJwt', ref: { $ref: 'vault', $id: '...' } }] — JWT stored as binary vault entry; on failure: empty array
• provider: keyless
• trustFramework: io.idnow.biometric (populated on success only; null otherwise)
• assuranceLevel: substantial (populated on success only; null otherwise)
• verifiedAt: ISO 8601 timestamp
• verificationProcessId: Keyless transaction ID