Generate Session Tokens for Youverify SDK Integrations

Every Youverify SDK flow — whether on web, Android, or iOS — requires a short-lived token generated from your backend before you can initialize the SDK on the client. This design ensures your secret API key never leaves your server and cannot be extracted from a web page or decompiled app.

Why server-side token generation is required

The Youverify SDK uses two separate tokens to authenticate a session:

Session ID — a short-lived identifier that scopes the session and links it to a specific user or entity record on your account.
Liveness token — an authentication token that authorizes the SDK to submit liveness data to Youverify’s verification infrastructure.

Both tokens are minted by the Youverify API using your secret API key. By generating them on your server, you keep the secret key out of client code entirely.

Do not generate these tokens in your mobile app or browser. Do not cache tokens across sessions. Generate fresh tokens immediately before each SDK initialization.

Endpoint 1 — Generate SDK Session ID

Use this endpoint for Web SDK flows and document capture sessions. POST /v2/api/sdk/session-id

Request

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",
    "ttlSeconds": 120,
    "metadata": {}
  }'

const response = await fetch(
  'https://api.youverify.co/v2/api/sdk/session-id',
  {
    method: 'POST',
    headers: {
      'token': process.env.YV_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      publicMerchantID: 'YOUR_PUBLIC_MERCHANT_ID',
      ttlSeconds: 120,
      metadata: {}
    })
  }
);
const { data } = await response.json();
const sessionId = data.sessionId;

import requests, os

resp = requests.post(
    'https://api.youverify.co/v2/api/sdk/session-id',
    headers={
        'token': os.environ['YV_SECRET_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'publicMerchantID': 'YOUR_PUBLIC_MERCHANT_ID',
        'ttlSeconds': 120,
        'metadata': {}
    }
)
session_id = resp.json()['data']['sessionId']

Request parameters

string

required

Your public merchant key from the Cowork dashboard.

number

default:"120"

How long the session ID remains valid, in seconds. Must be between 30 and 600. Defaults to 120.

object

default:"{}"

Optional key-value metadata to attach to the session, for example your internal user ID.

Response

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

string

The session ID to pass to the SDK constructor.

string

ISO 8601 timestamp when this session ID expires.

string

Always active on a successful response.

Endpoint 2 — Generate SDK Liveness Token

Use this endpoint for liveness detection flows on all platforms (Web, Android, iOS). POST /v2/api/sdk/liveness-token

Request

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

const response = await fetch(
  'https://api.youverify.co/v2/api/sdk/liveness-token',
  {
    method: 'POST',
    headers: {
      'token': process.env.YV_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      publicMerchantID: 'YOUR_PUBLIC_MERCHANT_ID',
      deviceCorrelationId: 'UNIQUE_DEVICE_OR_SESSION_ID'
    })
  }
);
const { data } = await response.json();
const livenessToken = data.authToken;

import requests, os

resp = requests.post(
    'https://api.youverify.co/v2/api/sdk/liveness-token',
    headers={
        'token': os.environ['YV_SECRET_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'publicMerchantID': 'YOUR_PUBLIC_MERCHANT_ID',
        'deviceCorrelationId': 'UNIQUE_DEVICE_OR_SESSION_ID'
    }
)
liveness_token = resp.json()['data']['authToken']

Request parameters

string

required

Your public merchant key from the Cowork dashboard.

string

A unique identifier for this device or user session. Use a UUID generated per session. This helps Youverify detect and prevent token reuse across devices.

string

An alternative device identifier from which Youverify can derive deviceCorrelationId. Use either deviceCorrelationId or deviceId, not both.

Response

{
  "success": true,
  "statusCode": 200,
  "message": "Liveness token fetched successfully!",
  "data": {
    "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "sessionId": "b15a8d20-c602-4f89-9d3a-1c3e4e5f6a7b"
  },
  "links": []
}

string

The liveness token to pass as sessionToken in the SDK constructor.

string

A session ID associated with this liveness token.

Token expiry and caching

Tokens are short-lived by design. Generate a fresh pair of tokens immediately before each SDK initialization. Do not store tokens in a database or cache for reuse across sessions.

If a token expires before the user completes the flow, the SDK’s onFailure callback fires with error.key = "invalid_or_expired_session". Your app should generate new tokens and re-initialize the SDK.

Scenario	What to do
`invalid_or_expired_session`	Generate a new session ID and liveness token; re-initialize the SDK
`session_token_error`	Generate a new liveness token; re-initialize the SDK
User retries after failure	The current session ID may still be valid; generate only a new liveness token

Get Started

Core Concepts

Guides

Webhooks

SDKs

Generate Session Tokens for Youverify SDK Integrations

Why server-side token generation is required

Endpoint 1 — Generate SDK Session ID

Request

Request parameters

Response

Endpoint 2 — Generate SDK Liveness Token

Request

Request parameters

Response

Token expiry and caching

​Why server-side token generation is required

​Endpoint 1 — Generate SDK Session ID

​Request

​Request parameters

​Response

​Endpoint 2 — Generate SDK Liveness Token

​Request

​Request parameters

​Response

​Token expiry and caching

Why server-side token generation is required

Endpoint 1 — Generate SDK Session ID

Request

Request parameters

Response

Endpoint 2 — Generate SDK Liveness Token

Request

Request parameters

Response

Token expiry and caching