Selfie Liveness Flow

Current Flow Version - v1.2

Available Since - 1 Mar 2026

Overview

Selfie Liveness is an SDK-integrated biometric security layer engineered to validate the physical presence of a user in real-time. Operating directly on the client device, it serves as a critical first line of defense against presentation attacks. By accurately distinguishing between a live human face and synthetic or inanimate reproductions, such as printed photos, digital screens, or 3D masks, the SDK ensures that the individual engaging with your platform is physically present and not a fraudulent actor utilizing stolen or generated media. To achieve maximum security with a frictionless user experience, our SDK integrates Aurora Liveness technology to perform passive liveness detection. This allows the system to instantaneously verify liveness during the image capture process without requiring the user to perform certain tasks (such as blinking, turning their head, opening their mouth, etc).

Common Use Cases

Pre-Validation for Identity Verification (eKYC)
Before a user's selfie and ID are sent to the backend for Face Matching, the Selfie Liveness SDK evaluates the user on the device. By catching spoofing attempts at the edge (e.g. someone pointing their phone camera at an iPad displaying a stolen photo), the system prevents fraudulent payloads from ever reaching your servers. This not only stops identity theft but also saves backend processing costs and API calls.
Secure Biometric Login & Account Recovery
When a user attempts to log in without a password or needs to recover a compromised account, they can use their face as their credential. Selfie Liveness ensures that an attacker cannot bypass the login screen by simply holding up a printed photograph or social media picture of the legitimate account holder. It guarantees that the actual user is holding the device at the exact moment of the login request.

High Level Flow

   sequenceDiagram
       autonumber
       title High Level SDK Flow Overview

       participant PFE as Partner FE
       participant PBE as Partner Backend Service
       participant DIS as Digital Identity SDK

       box rgb(240, 240, 240) IAB Infra
           participant TG as Token Gateway
           participant IBE as IAB Gateway
       end

       rect rgb(230, 245, 255)
           Note over PFE, TG: Get Partner token
           PBE->>TG: Get Partner token (client_id, passkey)
           TG-->>PBE: Partner token
           Note over PBE: Cache Partner token
       end

       PFE->>DIS: Initialize Digital Identity SDK

       rect rgb(230, 245, 255)
           Note over PFE, IBE: Get User token
           PFE->>PBE: Call initiate flow API
           PBE->>IBE: Initiate Flow (partner token, user_details)
           IBE-->>PBE: User token
           PBE->>PFE: User token
       end

       rect rgb(235, 230, 255)
           Note over PFE, IBE: Capture image and Submission processing
           PFE->>DIS: launchSelfieLiveness(user token, correlationId, baseUrl)
           Note over DIS: Capture Image Screens

           rect rgb(255, 245, 230)
               Note over DIS, IBE: Submission Processing
               DIS->>IBE: Start Submission Processing
               Note over IBE: Submission Processing
               IBE-->>PBE: Get Reference Image (User Details)
               PBE-->>IBE: Reference Image (URL)
               Note over DIS: Status Polling
               DIS->>DIS: Do next action:<br/>- RETRY<br/>- STATUS<br/>- EXIT
           end

           DIS->>PFE: on Completion(success/failure)
       end

       rect rgb(230, 245, 255)
           Note over PFE, IBE: Get Result Details
           IBE->>PBE: Submission Processing Compete Callback
           PFE->>PBE: Call "Get Submission Details" API <br/>(correlationId aka partner session id)
           PBE->>IBE: Call "Get Submission Details" API (correlationId, partner token)
           IBE-->>PBE: return submission details
           PBE-->>PFE: Continue processing
       end

       Note over PFE: Show/process result

Detailed Steps:

Partner BE call "Get Partner Token API" through IAB Gateway and caches the Partner Token to be used repeatedly.
1. Partner FE calls Partner BE to get User Token. Partner BE calls IAB Gateway to get user Token using the Initiate Flow API.
  1. Partner User Id
  2. Partner User Id Type
  3. Onboarding partner tied to the flow, which partner wants to launch.
2. Partner FE initializes the Digital Identity FE SDK (IAB FE):
  
  Use the initialise method to initialize the SDK.
3. Partner FE calls launchSelfieLiveness() method of Digital Identity SDK to launch Selfie Liveness flow with the following parameters:
  1. baseURL: This is the server URL specific to the partner using the format https\://<domain>.
    Example: https://onekyc.ky.id.sandbox.gopayapi.com
  2. correlationId: A unique ID used to create a Selfie Liveness request and track the specific instance of the Selfie Liveness request helpful for logging and event tracking.
  3. token: The unique user token, different for each user.
  4. theme(optional): The theme parameter is optional, and its default value is null. If not provided, the SDK uses the default theme (DefaultOneKycSelfieLivenessFlowTheme).
    The theme parameter is an instance of the OneKycSelfieLivenessFlowTheme class. It allows you to customize the look and feel of the Selfie Liveness flow screen. By providing a custom theme, you can modify various UI elements, such as colors, fonts, and styles, to match your application's branding requirements.
4. IAB FE will capture users' selfies and will upload it to IAB Gateway for Liveness processing.
5. IAB Gateway initiates Liveness processing.
6. Meanwhile, the IAB FE will continuously poll the IAB Gateway to check the processing status and display a loader to the user until the process is complete.
7. Once the processing is complete, the IAB FE will redirect the user back to the Partner FE using the resultCallback(DocumentVerificationResult) method.

Integration Contracts

Document Name	Link
BE API Guide	BE API Guide
Web SDK Guide	Web SDK Guide
Android SDK Guide	Android SDK Contract
Flutter SDK Guide	Flutter SDK Contract
iOS SDK Guide	iOS SDK Contract

Updated 8 days ago