Integrate Youverify Web SDK for Browser-Based Verification

The Youverify Web SDK lets you embed liveness detection and document capture directly in your web application — no redirect to a hosted page required. The SDK is compatible with all major browsers and devices. Before launching any SDK flow you must generate a session token from your backend to keep your secret API key off the client.

Installation

Choose either the npm package or the CDN script tag, depending on whether your project uses a Node.js-based build pipeline.

npm
CDN (jsDelivr)
CDN (UNPKG)

Install the package for your chosen flow:

# Liveness detection
npm install youverify-liveness-web

# Document capture
npm install youverify-sdk

Add the script tag directly to your HTML if you are not using a Node.js build pipeline:

<!-- Liveness Web SDK -->
<script src="https://cdn.jsdelivr.net/npm/youverify-liveness-web/dist/index.js"></script>

<!-- Document Capture SDK -->
<script src="https://cdn.jsdelivr.net/npm/youverify-sdk/dist/index.js"></script>

<!-- Liveness Web SDK (latest) -->
<script src="https://unpkg.com/youverify-liveness-web/dist/index.js"></script>

<!-- Liveness Web SDK (pinned version) -->
<script src="https://unpkg.com/youverify-liveness-web@1.0.1/dist/index.js"></script>

Integration steps

Generate a session ID server-side

Your backend calls the Youverify API to generate a short-lived session ID. This call uses your secret API key — it must happen on your server, not in the browser.

curl -X POST "https://api.youverify.co/v2/api/sdk/session-id" \
  -H "token: $YV_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publicMerchantID": "YOUR_PUBLIC_MERCHANT_ID",
    "metadata": {}
  }'

Response:

{
  "success": true,
  "statusCode": 200,
  "message": "SDK session generated",
  "data": {
    "sessionId": "200f5a883713b7ff26f22f489d716ca3",
    "expiresAt": "2025-10-05T23:56:48.821Z",
    "status": "active"
  },
  "links": []
}

Pass the session ID to your front-end

Return the sessionId from your backend API to the browser. You might expose a thin endpoint on your own server for the browser to call, for example GET /api/verification-session.

Initialize the SDK

Construct the SDK instance with your public merchant key and the session ID. Register your callbacks before calling launch().

const yvSDK = new YouverifySDK({
  publicMerchantKey: 'YOUR_PUBLIC_MERCHANT_KEY',
  sessionId: sessionId,         // from your backend
  sandboxEnvironment: false,    // set to true for testing
  onSuccess: (data) => {
    console.log('Verification complete', data);
    // Update your UI and notify your backend
  },
  onError: (error) => {
    console.error('Verification failed', error);
  },
  onClose: () => {
    console.log('User closed the verification flow');
  }
});

Launch the verification flow

Call launch() when your user is ready to start — for example, on a button click.

document.getElementById('verify-btn').addEventListener('click', () => {
  yvSDK.launch();
});

Callbacks

Callback	When it fires	Argument
`onSuccess`	All verification tasks completed successfully	Result data object
`onError`	A task failed or an error occurred	Error object with `key` and `message`
`onClose`	The user dismissed the SDK modal	None

Configuration options

string

required

Your Youverify public merchant key. Safe to embed in browser code. Retrieve it from Settings → API KEY / Webhook in the Cowork dashboard.

string

required

The short-lived session ID generated by your backend. See Session Tokens.

boolean

default:"false"

Set to true to run in sandbox mode using test data. Set to false for production.

function

Callback invoked when the user successfully completes the verification flow. Receives a result data object.

function

Callback invoked when verification fails or an error occurs. Receives an error object.

function

Callback invoked when the user closes the SDK modal without completing the flow.

How results link back to your entity

The session ID you generate is tied to the verification result on Youverify’s side. After the SDK flow completes, call your backend to retrieve the result using the Liveness History endpoint or by reading the entity record via the API. The session ID is the join key between the SDK-collected biometric data and your entity record.

Session IDs are short-lived (default TTL: 120 seconds, configurable between 30 and 600 seconds). Generate a fresh session ID for each verification attempt — do not cache or reuse them.

Never pass your API secret key to the Web SDK. Use only your public merchant key on the client side. Your secret key must remain on your server.

Get Started

Core Concepts

Guides

Webhooks

SDKs

Integrate Youverify Web SDK for Browser-Based Verification

Installation

Integration steps

Callbacks

Configuration options

How results link back to your entity

​Installation

​Integration steps

​Callbacks

​Configuration options

​How results link back to your entity

Installation

Integration steps

Callbacks

Configuration options

How results link back to your entity