Init

Endpoint Overview

POST /api/v1/liveness-sdk/init

Description

This endpoint initializes the Liveness SDK session, which enables face liveness detection to verify that a real person is present during the verification process. The initialization configures various parameters for the liveness check, such as eye blink detection, voice assistance, and frame size, and returns a client ID and token required for subsequent API calls.

Key Benefits

Prevents identity fraud by ensuring a real person is present during verification

Customizable verification parameters to suit different security requirements

Configurable user experience with options for voice assistance and frame size

Flexible token management with customizable expiry times

Use Cases

Financial Services

Identity Verification

Access Control

Remote customer onboarding for banking and financial applications

Secure authentication for high-value transactions

KYC verification for fintech platforms and digital wallets

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT
Content-Type	Yes	application/json

Request Body

Request Parameters

Parameter	Type	Required	Description
voice_token	Boolean	No	Voice Token
eye_bling	Boolean	No	Eye Bling
eye_blink	Boolean	No	Eye Blink
assist_voice	Boolean	No	Assist Voice
location_check	Boolean	No	Location Check
movement_check	Boolean	No	Movement Check
step_duration	Integer	No	Step Duration
frame_size	String	No	Frame Size
head_movement_attempts	Integer	No	Head Movement Attempts
token_expiry	Integer	No	Token Expiry
reference_id	String	No	Reference Id
disable_audio	Boolean	No	Disable Audio
smile_check	Boolean	No	Smile Check
redirect_url	String	No	Redirect Url

Example Request

{
    "eye_blink": true,
    "head_movement_attempts": 4,
    "frame_size": "medium"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the client_id and token required for subsequent API calls
data.client_id	String	Unique identifier for the liveness session
data.token	String	JWT token for authenticating subsequent requests in this session
status_code	Integer	HTTP status code indicating the result of the request
success	Boolean	Indicates whether the request was successful
message	String or null	Additional information about the response (null if successful)
message_code	String	Code indicating the status of the operation

Example Successful Response

{
    "data": {
        "client_id": "liveness_sdk_onadfasvadbnadtUbTANnMbBxZ",
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTadfasdfadsgsadcadsgasvsagahrnyfjsfbdfdbavarvaS_M"
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Validation Error

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Invalid authentication token",
    "message_code": "authentication_error"
}

This error occurs when the provided JWT token is invalid, expired, or missing.

Integration Best Practices

Security Recommendations

Store the client_id and token securely as they provide access to the liveness verification session

Implement proper token lifecycle management, considering the token_expiry parameter

Use HTTPS for all API communications to ensure data encryption in transit

Implement rate limiting on your client side to prevent abuse

User Experience Guidelines

Enable voice assistance (assist_voice) for first-time users to improve completion rates

Choose an appropriate frame_size based on the device screen size for optimal user experience

Set a reasonable step_duration that balances security with user convenience

Consider disabling audio recording (disable_audio) in environments where privacy is a concern

Code Samples

cURL

Python

Node.js

Related APIs

Liveness SDK Verification: Processes the liveness verification after initialization

Liveness SDK Status: Checks the status of a liveness verification session

Liveness SDK Result: Retrieves the final result of a completed liveness verification

Compliance and Legal Considerations

When implementing liveness detection, be aware of biometric data privacy regulations such as GDPR in Europe, BIPA in Illinois (USA), and similar laws in other jurisdictions. Ensure proper user consent is obtained before collecting facial biometric data, and clearly communicate how this data will be used, stored, and protected. Consider implementing data minimization practices and providing users with options to delete their biometric data.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/liveness-sdk/init' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "eye_blink": true, "head_movement_attempts": 4, "frame_size": "medium" }'

{ "data": { "client_id": "liveness_sdk_onadfasvadbnadtUbTANnMbBxZ", "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTadfasdfadsgsadcadsgasvsagahrnyfjsfbdfdbavarvaS_M" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Init

Init#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Request Parameters#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Init

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Request Parameters

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples