Server-Side Session Initiation

This guide explains how to initiate a verification session on the server side and securely hand it off to a mobile application.

Why Use Server-Side Initiation?

Security: API keys remain on the backend and are never exposed to the client.
Identity linking: Your system’s external_user_id is securely linked to the IDV session.

Prerequisites

Authorization: Familiarity with the main authorization methods.
API credentials: An API key with the permission Ephemeral Devices:Write, issued and stored securely on your backend.

Flow

The flow consists of the user initiating the action on the client, your backend creating a secure container (ephemeral device), your backend starting a session, and then passing a session token back to the client.

The IDV flow

Step 1: Start verification

The user clicks Start Verification on your mobile or web application. Your app sends a request to your backend to initiate the process.

Step 2: Create ephemeral device

Your backend uses its secure API key to create an ephemeral device on the IDV platform. This step is crucial to isolate user data from other data on the IDV platform.

Request:

curl --location 'https://<IDV_HOST>/api/device/ephemeral' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <api_key>' \
  --data '{ "ttl": 3600 }'

Response:

{
  "authorization": "<token>"
}

Step 3: Start session

Using the authorization token received in the previous step (not your main API key), your backend initiates a session for a specific workflow. This allows you to bind the session to a known external_user_id.

Request:

curl --location 'https://<IDV_HOST>/api/sessions?workflowId=<workflow_id>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <token>' \
  --data '{ "metadata": { "externalUserId": "<external_user_id>" }}'

Step 4: Return handoff URL to client

Once the session is started, your backend must construct a specific URL and return it to the mobile or web application.

Format: https://<IDV_HOST>/capture?url=<URL_ENCODED_LINK>

Example Construction:

https://<IDV_HOST>/capture?url=<url-encoded(
  "https://<IDV_HOST>/mobile?authorization=<token>&sessionId=<sessionId>"
)>

Step 5: Token-based initialization (client side)

The mobile application receives the URL or token and uses the SDK to initialize the flow.

For detailed implementation instructions, refer to the developer documentation:

iOS
Android