Secure and seamless real-time liveness verification.The Liveness Streaming is an innovative solution that enables real-time liveness verification directly on your website or application. With a simple and fast integration, you can incorporate this functionality into your operation, ensuring security and efficiency in the user authentication process and supporting digital identity verification.
How does it work?#
Liveness Streaming uses a real-time selfie video to detect and prevent fraud attempts, such as printed photos, digital images, pre-recorded videos, deepfakes, or even 3D masks. The solution is designed to analyze the video instantly, minimizing latency and providing results within a few seconds.Key features:#
Ready-to-use and customizable interface: We provide a pre-configured user interface with a neutral design that can be easily integrated into your application, accelerating implementation.
Simple and intuitive interaction: The user performs the liveness verification by positioning their face within an oval shape displayed on the device screen, similar to taking a selfie. During the process, the user is prompted to perform movements that ensure proximity and interaction with the camera.
Real-time analysis: The video is analyzed instantly to detect potential fraud, verifying whether the liveness check is being performed by a real person who is present at the time of capture.
Reliable results: The solution generates a livenessScore (confidence score) ranging from 0 to 1, where a higher score indicates greater confidence that the user is live and genuine. In addition, a frontalImage (frontal image) is captured during the process and can be used in face matching processes.
Multiple options for accessing results: Results can be obtained via webhook or queried directly through the status endpoint, providing flexibility to fit your workflow.
Why choose Liveness Streaming?#
Advanced security: Detects and prevents a wide range of fraud attempts, ensuring user authenticity.
Fast integration: With a pre-built interface and detailed documentation, implementation is simple and efficient.
Optimized user experience: An intuitive process and results within seconds, without compromising usability and reducing friction for end users.
Scalable and reliable: Designed for large-scale operations, with low latency and high accuracy.
Minimum client device requirements (User-Side Liveness)#
For the Liveness service to run correctly, the end user's device must meet the following minimum specifications:Device and display specifications#
| Category | Minimum Requirement |
|---|
| Camera | Front-facing camera required (must be color). |
| Display refresh rate | Minimum of 60 Hz. |
| Screen size | Minimum of 4 inches. |
| OS security | The device must not be jailbroken (iOS) or rooted (Android). |
Camera and video capture specifications#
| Category | Minimum Requirement |
|---|
| Recording resolution | Minimum of 480x640px. |
| Frame rate | Minimum of 15 frames per second (fps). |
| Camera type | Virtual cameras or simulated camera software are not supported. |
| Desktop use | For webcam use on desktop computers, the camera must be mounted at the top of the same monitor where the verification is initiated. |
Connectivity and software specifications#
| Category | Minimum Requirement |
|---|
| Bandwidth | Minimum of 100 kbps. |
| Supported browsers | The latest three versions of the major browsers (Google Chrome, Mozilla Firefox, Apple Safari, and Microsoft Edge). |
Configuration parameters (settings)#
When creating a session through the Liveness Streaming [application/json] route (POST /liveness/streaming/async), you can send a settings object with additional configurations that change how the liveness check behaves. All parameters are optional and can be combined in the same request.| Parameter | Type | Purpose |
|---|
setSystemClockOffset | Boolean | Compensates for differences between the device clock and the server clock. |
frameAncestors | Array of strings | Defines which domains can embed the liveness interface in an iframe. |
Example with both parameters:"settings": {
"setSystemClockOffset": false,
"frameAncestors": ["app.yourcompany.com"]
}
Clock Synchronization (System Clock Offset)#
The setSystemClockOffset parameter makes the liveness check more resilient on devices whose system clock is incorrect or out of sync with the verification servers."settings": {
"setSystemClockOffset": true
}
How it works#
In video streaming and biometric security processes, timestamp accuracy is essential. By default, the system uses the time on the user's device. If there is a significant difference (clock skew) between the device time and the server time, the liveness session may be invalidated for security reasons, resulting in an error like the one below:{
"result": {
"processId": "2de80502-f4fe-4e6b-93ee-53d9474f26ca",
"status": "ERROR",
"statusDescription": "Server and device clocks are out of sync",
"livenessScore": null,
"frontalImage": null
},
"requestId": "Y8XfDzvy5k2KoGLv67C79",
"elapsedMilliseconds": 677,
"status": {
"message": "Ok",
"code": "200",
"errors": null
}
}
setSystemClockOffset is enabled, the system automatically calculates the difference between the local clock and the server clock at the start of the session, adjusting the requests so that the time difference does not cause the liveness check to fail.Accepted values#
| Value | Behavior |
|---|
false or parameter not sent | Default behavior. The device time is compared with the server time, and if there is a considerable difference, the liveness check will fail. |
true | The system applies an offset based on the server time, allowing the analysis to run normally even on devices with incorrect date and time settings. |
When to use it#
We recommend setting it to true only in scenarios with a high rate of technical errors of the type "Server and device clocks are out of sync". This ensures a better user experience and prevents users from being blocked because of an incorrect setting on their own device.Iframe embedding (frameAncestors)#
The Liveness Streaming web interface can be embedded in an iframe within your application. For security reasons, to prevent attacks such as clickjacking, only pre-authorized domains can display the liveness page in an iframe.The frameAncestors parameter defines, per session, which of these authorized domains can embed the page."settings": {
"frameAncestors": ["app.yourcompany.com", "*.yourcompany.com"]
}
⚠️ Important: domains must be pre-approvedTo embed the interface in an iframe, your application's domains must be registered in your account's list of approved domains. Without this registration, the page cannot be embedded, even if the frameAncestors parameter is not sent.To request the registration, contact our support team and send the list of domains you need.
Accepted values#
| Value sent | Behavior |
|---|
Parameter not sent or null | The page can be embedded by all domains registered for your account. If the account has no registered domains, the page cannot be embedded. |
List of domains, e.g. ["app.yourcompany.com"] | The page can only be embedded by the listed domains, which must be registered for your account. |
[] (empty list) | The page cannot be embedded in any iframe. |
Value that is not a list (e.g. "yourcompany.com") | Session creation error (HTTP 400, code R101). |
| List containing an unregistered domain | Session creation error (HTTP 400, code R101). |
Domain format#
Each item in the list must follow one of these formats:| Format | Example |
|---|
| Full domain | app.yourcompany.com |
| Wildcard for subdomains | *.yourcompany.com |
The value must always be a list, even with a single domain: use ["yourcompany.com"], not "yourcompany.com".
The https:// prefix is optional and is removed automatically.
A maximum of 20 domains is allowed per session.
The following are not accepted: a standalone *, keywords such as 'self' or 'none', schemes (https:, data:), addresses with http://, ports, paths (e.g. /page), spaces, or ;.
💡 About wildcards: registering *.yourcompany.com allows subdomains such as portal.yourcompany.com, but does not allow the root domain yourcompany.com. If you need both, request registration for both.
Session creation errors#
When frameAncestors is invalid, the session is not created and the API returns HTTP 400 with code R101. The errors field indicates the parameter that caused the problem and the reason it was rejected.Message in errors | Cause | How to fix it |
|---|
frameAncestors is not of an expected type | The value sent is not a list (e.g. "yourcompany.com"). | Send the domains as a list: ["yourcompany.com"]. |
The frameAncestors field contains hosts not allowed for this account | One or more domains in the list are not registered for your account or are in an unsupported format. | Check the domains sent and the accepted format. To add new domains, contact our support team. |
Example response when the value is sent as text instead of a list:{
"result": null,
"requestId": "ZnBcGfuGxA8ojRaQV4cxz",
"elapsedMilliseconds": 503,
"status": {
"message": "A specified parameter is wrong",
"code": "R101",
"errors": [
{
"field": "frameAncestors",
"message": "frameAncestors is not of an expected type"
}
]
}
}
{
"result": null,
"requestId": "UopYShZ6OOsMaSOg7SNzf",
"elapsedMilliseconds": 2930,
"status": {
"message": "A specified parameter is wrong",
"code": "R101",
"errors": [
{
"field": "frameAncestors",
"message": "The frameAncestors field contains hosts not allowed for this account"
}
]
}
}
Specific situations#
Invalid or expired link: if the page is accessed without a session or with an invalid or expired link, it cannot be embedded in any iframe.
Protected configuration: the domain list is securely bound to the session and cannot be changed by the end user.
Camera permission in the iframe#
For the camera to work inside the iframe, the <iframe> tag must grant this permission through the allow attribute. Without it, the browser blocks camera access and the liveness check ends with the "Camera access error" error.In the allow attribute, specify the origin of the liveness session link, always with the https:// prefix:Embedding through another application (nested iframes)#
In some flows, the liveness check is opened inside an application that is itself embedded in an iframe. For example:portal.yourcompany.com (main page)
└── partner-app.com (application in an iframe)
└── liveness.mostqi.com (liveness check in an iframe)
<iframe> in the chain must allow the camera for all origins below it:On the main page (portal.yourcompany.com):On the intermediate application (partner-app.com):If any level leaves the Liveness Streaming origin out of the allow attribute, the camera permission is lost at that point in the chain.2. Every domain in the chain must be authorized in frameAncestors. The browser validates every level above the liveness page, not only the iframe immediately above it. Therefore, both the main page and the intermediate application must be registered for your account and, if the parameter is sent, included in the list:"settings": {
"frameAncestors": ["portal.yourcompany.com", "partner-app.com"]
}
Statuses and error messages#
Possible statuses and descriptions in the API response#
| Status | statusDescription | Details |
|---|
| TODO | "Waiting for user interaction" | The liveness verification has not yet started. The session is available to start the process. |
| DOING | "User interaction in progress" | The liveness verification has started and the process is in progress. |
| DONE | "User interaction completed successfully" | The liveness verification has been completed. In this case, the result will include values for the frontalImage and livenessScore attributes, if available, which should be evaluated to determine the final liveness verification result. |
| EXPIRED | "User did not interact within the time limit" | The liveness verification session has expired. This occurs when the user does not complete the liveness verification within 3 minutes after clicking "Start capture". |
| CANCELED | "Canceled after 1 hour of inactivity" | The liveness verification session was canceled because it was not completed within the maximum inactivity period of 1 hour. |
| ERROR | "Camera access error" | The device camera could not be accessed. Check whether camera permission is enabled in the browser or device settings. |
| ERROR | "Camera framerate error" | The camera is unable to capture images at the required minimum frame rate. |
| ERROR | "Default camera not found" | No camera was found on the device. Check whether the device has an available camera and whether it is working correctly. |
| ERROR | "Liveness session has expired. Please create a new session." | The verification session has expired. Please start a new session to continue the process. |
| ERROR | "Face distance error" | The face is too close to or too far from the camera. Adjust the device position until the face is properly framed on the screen. |
| ERROR | "The security token included in the request is invalid." | The request security token is invalid or has expired. |
| ERROR | "Server and device clocks are out of sync" | The device time differs from the server time. Check whether the device date and time are configured correctly. |
| ERROR | "Device orientation error" | The device orientation is incorrect. Position the phone according to the orientation indicated on the screen to continue. |
| ERROR | "Multiple faces error" | Multiple faces were detected by the camera. Make sure that only one person is visible in the frame. |
| ERROR | "Liveness session has results available. Please get results for the session." | This verification session already has results available. Use the results query to retrieve the session information. |
| ERROR | "Unexpected runtime error" | An unexpected error occurred during the process. Please try again in a few moments. |
| ERROR | "Unexpected server error" | An unexpected server error occurred. Please try again later. |
| ERROR | "Connection timed out" | The connection timed out. Check your internet connection and try again. |
Messages displayed in the interface#
While using the Liveness Streaming web interface, users may see different messages depending on when the issue occurs or the current state of the session.The messages can be classified as:Errors during the liveness verification: occur while the process is running and usually indicate a condition related to the device, camera, connectivity, or processing.
Session status messages: displayed when the user accesses the link of a session that has already been started, completed, expired, or ended with an error.
Result messages: displayed at the end of the liveness verification and indicate whether the user's liveness has been confirmed.
Important: only a session with TODO status is available to start the liveness verification flow. Sessions with other statuses cannot be restarted using the same link.
Example of how an error message is displayed to the user in the Liveness Streaming solution interface
What should I do when an error message is displayed?Request a new verification: for most errors that occur during the liveness verification, the current session should not be reused.
Check the device: for errors related to the camera, orientation, face distance, or frame rate, check the device conditions and instruct the user to try again using a new session.
Check the date and time settings: for errors related to signing or clock synchronization, confirm that the device date and time are configured correctly. If this issue occurs repeatedly, check the setSystemClockOffset configuration.
Errors during the liveness verification#
These errors may be displayed in real time while the liveness verification is in progress. Depending on the error, the session may be terminated and a new process must be started (a new link must be requested through the API).| Title displayed in the interface | Detail displayed in the interface | When it may occur |
|---|
| Connection timed out | A connection timeout error occurred during liveness verification. Please request a new verification. | May occur when the communication required to perform the liveness verification exceeds the expected timeout. For the user, the handling is the same as in the Connection timed out scenario: request a new verification. |
| Connection timed out | A connection timeout error occurred during liveness verification. Please request a new verification. | Occurs when the process exceeds the timeout defined for an operation. The interface displays the same Connection timed out message. |
| Unexpected error | An unexpected error occurred during liveness verification. Please request a new verification. | May occur when an unexpected failure occurs during the process that does not fit into any of the other specific error types. |
| Camera frame rate error | A camera frame rate error occurred during liveness verification. Please request a new verification. | May occur when the camera cannot capture at the required minimum frame rate. The technical documentation establishes a minimum of 15 fps for video capture. |
| Camera access error | A camera access error occurred during liveness verification. Make sure the camera is connected and that the browser has permission to access it. Please request a new verification. | May occur when the browser or device does not allow camera access, for example, when permission has not been granted or has been blocked. The interface requests this permission before capture begins. |
| Face distance error | A face distance error occurred during liveness verification. Make sure your face is centered and at an appropriate distance from the camera. Please request a new verification. | Occurs when the face is too close to or too far from the camera, preventing proper capture. |
| Device orientation error | A device orientation error occurred during liveness verification. Please keep your device in portrait orientation during the verification. Please request a new verification. | May occur when a mobile device is being used in landscape orientation instead of portrait orientation. |
| Multiple faces error | A multiple faces detection error occurred during liveness verification. Make sure that only one person is in front of the camera during the verification. Please request a new verification. | Occurs when more than one face is detected in the camera frame. |
| Default camera not found error | A default camera error occurred during liveness verification. Make sure that a camera is connected and configured as the default camera on your device. Please request a new verification. | May occur when the device does not have an available camera or when no valid camera is configured as the default. |
| Server error | A server error occurred during liveness verification. Please try again later. | May occur when an unexpected failure occurs while processing the service. |
| Invalid signature | The signature provided for this liveness verification is invalid. This occurs when the server and device time are out of sync. | May occur when there is a significant difference between the user's device clock and the clock used by the server. The documentation recommends considering setSystemClockOffset for scenarios with a high occurrence of this issue. |
Messages displayed when accessing the session link#
When accessing the liveness verification link, the interface checks the current status of the session.Only sessions with TODO status can normally start the flow. Other statuses indicate that the session is already in progress, has been completed, has expired, or has been terminated.
| Status | Title displayed in the interface | Detail displayed in the interface | When it may occur |
|---|
DOING | Session in progress | This session is already in progress. Please wait. | Occurs when the user accesses the link of a session that has already been started and is still being processed. The DOING status represents a session in which the user has already clicked Start capture. |
DONE | Session completed | This session has already been completed. You can close this window now. | Occurs when the liveness verification has already been completed and the session has a result available. A new liveness verification should not be started using the same link. |
ERROR | Invalid session | An error occurred during the liveness verification process. Please request a new verification. | Occurs when the session has been terminated with an error. For example, the verification may have ended due to a camera issue, timeout, or another technical error. When attempting to access the same link again, the interface displays this message instead of allowing a new attempt. |
EXPIRED | Session expired | This session has expired. Please request a new verification. | Occurs when the user does not complete the liveness verification within the time allowed for the session. Currently, the documentation states a limit of 3 minutes after capture begins. |
CANCELED | Session expired | This session has expired. Please request a new verification. | Occurs when the session remains incomplete until reaching the maximum inactivity period of 1 hour. |
Example: ERROR and the "Invalid session" message#
A session may reach the ERROR status after a liveness verification attempt is terminated due to a technical error.1
User starts the liveness verification
2
A camera error or timeout occurs
3
Session is terminated with ERROR status
4
User attempts to access the same link again
5
Interface displays "Invalid session".
The link must not be reused. In this scenario, a new request must be made to start a new liveness verification process.
Messages displayed at the end of the liveness verification#
These messages do not necessarily represent a technical error. They represent the result of the analysis performed by the liveness verification.| Title displayed in the interface | Detail displayed in the interface | When it occurs |
|---|
| Success! | We successfully confirmed the user's liveness. Thank you for completing the process! | Occurs when the analysis confirms the user's liveness. |
| Almost there! | We could not confirm the user's liveness. Please request a new verification. | Occurs when the analysis cannot confirm the user's liveness. In this case, a new verification should be requested. |
The API returns livenessScore and frontalImage, when available, after the liveness verification is completed. The client is responsible for using this information according to its business flow.
Usage tracking#
Usage for the Liveness Streaming product is counted only for requests completed with the "DONE" status. These requests will be included in usage and billing reports.Use cases#
Combine Liveness Streaming with our other solutions to create a complete and secure identity verification flow:1.
Document data extraction: Use the Content Extraction endpoint to automatically extract data and the photo from an identity document (such as an ID card, driver's license, or passport). 3.
Face matching: Finally, use the Face Compare 1:1 endpoint to compare the document photo with the image captured during the liveness verification, ensuring that the person who performed the liveness verification is the same person shown in the document. Use case scenarios:#
Digital onboarding for financial institutions#
Use Liveness Streaming to verify the identity of new customers during registration at banks or fintech companies, combining liveness verification with document data extraction and face matching. This reduces fraud and speeds up the account opening process.Authentication for high-value transactions#
For financial transactions or sensitive operations, Liveness Streaming can be used as an additional security layer, confirming the user's presence and authenticity before authorizing the operation.Authentication in urban mobility applications#
Transportation or vehicle-sharing companies can implement the solution to verify the identity of drivers and passengers, ensuring that the registered person is the same person using the service. This increases security and trust in the platform.Educational institutions can use the solution to verify students' identities during online tests or examinations, ensuring the integrity of the assessment process.Check-in for events or travel#
Travel companies or event organizers can implement Liveness Streaming to validate participants' identities during check-in, whether at hotels, airports, or in-person events.Access control in companies#
Liveness Streaming can be integrated with physical or logical access control systems, replacing passwords or identification cards. Employees or visitors perform real-time liveness verification to access restricted areas or internal systems, ensuring greater security.Identity verification in online gaming and eSports#
Online gaming platforms or eSports tournaments can use Liveness Streaming to ensure that participants are who they claim to be, preventing fraud such as shared accounts or professional players participating in amateur categories.Clinics, hospitals, and telemedicine platforms can use Liveness Streaming to validate patients' identities during virtual consultations or when accessing electronic medical records. This ensures that only the actual patient has access to sensitive information and medical services. 
