Secure video liveness

Live KYC requires a backend-verified Amazon Rekognition Face Liveness video session. This also applies to the individual identity check for a KYB signatory. A selfie upload, two still frames, a client-selected gesture, a browser callback or a manual approval cannot satisfy this requirement. Sandbox responses remain explicitly simulated and provide no biometric assurance.

This is a breaking change for integrations that submit live KYC using only images. Use the hosted flow through REST, the private 2.0.0 SDK source release, or the secure capture protocol below. Private 2.0.0 source tags are available; public registry packages are not published; see SDK access. Existing records retain their historical evidence; they are not relabeled as video verified.

Recommended integration

1. Your backend calls POST /v1/sessions/create with its API key and your user's stable userId.
2. Open the returned verifyUrl in the user's browser. React/React Native applications can use YeboVerifyHosted; Swift provides YeboVerifyHostedLink, Kotlin provides hostedVerificationIntent, and Flutter provides YeboVerifyHosted with a host-app openBrowser callback. All open the same backend-created URL using the platform browser.
3. The user consents to biometric capture and completes the video face-and-light challenge, then photographs their ID.
4. Your backend receives the signed result webhook or reads the verification result using its API key. Browser navigation and client callbacks are not authoritative results.

Keep live API keys off websites, browser storage, mobile bundles and end-user devices. The older image-capture widgets are now sandbox only and refuse live keys before capture. They are not an alternative route to live approval.

The hosted capture surface works on supported desktop and mobile browsers. A mobile browser does not provide native app/device attestation. This release does not claim Apple App Attest or Android Play Integrity enforcement, and a phone or user-agent string is not evidence of genuine capture.

Custom video integration

Use these APIs from a trusted backend. End-user capture receives only the temporary session response, never the customer API key.

const capture = await client.createLivenessSession(user.id, true);
// Pass capture to a supported AWS Face Liveness capture component.
// After video capture, ask your backend to fetch and verify the AWS result:
await client.completeLivenessSession(user.id, capture.livenessSessionId);
const verification = await client.verify({
  externalRef: user.id,
  livenessSessionId: capture.livenessSessionId,
  idFront,
  idBack,
  idempotencyKey: attemptId,
});

The same create/complete methods are available in Node, React Native, Flutter, Swift and Kotlin clients. They are backend/proxy integration helpers; calling them does not itself capture video. For React, SecureLivenessCapture accepts backend createSession and completeSession callbacks and reports a proof ID only after the backend accepts the provider result. The hosted app reuses this component.

Endpoint	Authentication	Body
POST /v1/liveness/sessions	Live API key	{ externalRef, consent: true }
POST /v1/liveness/sessions/complete	Live API key	{ externalRef, livenessSessionId }
POST /v1/sessions/liveness	Signed hosted token in body	{ session, consent: true }
POST /v1/sessions/liveness/complete	Signed hosted token in body	{ session, livenessSessionId }

These endpoints return the normal { success, data } envelope. Creation returns livenessSessionId, provider sessionId, region, expiresAt, and temporary capture credentials. Completion returns only { livenessSessionId, verified: true }. Scores and reference/audit images are not returned to the capture browser. Never treat onAnalysisComplete as a passing result: the backend retrieves the result directly from AWS.

POST /v1/verify and synchronous POST /v1/verify/id-document both require livenessSessionId and the same externalRef for live KYC. The authoritative selfie is extracted from the verified video by the provider. Uploading another selfie cannot replace it. The standalone /v1/verify/selfie-match utility reports image similarity and must not be treated as full KYC or live-person verification.

Server enforcement

• Capture sessions expire after at most three minutes. A completed passing proof can be submitted for ten minutes.
• Proofs belong to one business and person. Hosted proofs additionally belong to the exact signed action token; renewing a token requires a new liveness check.
• Consumption is atomic with verification admission. A proof cannot verify a second document or another person, even if a caller changes image bytes. Retry a submitted attempt using the same idempotency key.
• Only a successful face-and-light provider challenge above the platform threshold can create a proof. Missing results, a weaker challenge, failed results and provider outages never become a pass.
• Issued attempts are limited to five per person per rolling hour and sixty per business per rolling hour. IP and authenticated-business rate limits apply across instances. Rotating an arbitrary API-key header on an anonymous endpoint does not reset them. A counter-store outage fails closed.
• Temporary AWS credentials can only start capture streams in the selected region during the capture window. They cannot create provider sessions, retrieve results or access stored evidence.
• Pending reference images are encrypted using AES-256-GCM and cleared on consumption, expiry cleanup or subject erasure. Accepted evidence follows the case's normal evidence lifecycle.
• Customer thresholds cannot weaken platform minimums: automatic approval face 80 / OCR 60; entry to manual review face 60 / OCR 50. Customers can raise these thresholds or require manual review for otherwise eligible cases. Video liveness cannot be disabled.

Case details and result webhooks include securityVersion and livenessProvider. Version 2 with aws-rekognition-face-liveness identifies this capture protocol. A sandbox result, or an older record with no provider identity, must not be presented as a passing video-liveness check.

Errors and recovery

Error	Meaning
428 SECURE_LIVENESS_REQUIRED / LIVENESS_NOT_VERIFIED	Complete video liveness first.
403 LIVENESS_PROOF_INVALID	Proof does not belong to this customer/person/session.
409 LIVENESS_PROOF_ALREADY_USED	New attempt requires new capture; retry the original submission with its original idempotency key.
410 LIVENESS_EXPIRED	Perform a new liveness check.
422 LIVENESS_FAILED	The provider result did not meet the security requirement.
429 LIVENESS_ATTEMPTS_EXCEEDED	Wait for the attempt window or contact support.
503 LIVENESS_UNAVAILABLE	Provider/configuration unavailable. Do not substitute a still-image check or fabricate an approval.

What this does and does not prove

This adds defenses against photo/video replay and injected or AI-generated face media. It does not guarantee detection of every deepfake. The configured thresholds need evaluation on representative devices, lighting, skin tones, accessibility needs and current attacks. Unit tests and synthetic provider results verify our API enforcement, not a measured attack rejection rate.

Liveness also does not prove that an identity document is authentic. OCR extracts fields; it is not an issuer database check, cryptographic NFC chip verification or a certified document-forensics service. Those checks require separate evidence and integration. Do not describe this release as an independently certified end-to-end KYC system.

AWS references: Face Liveness, usage recommendations, and service limitations.