Token URL

This authentication method is used when you start a session server-side and want to hand off a tokenized URL to a client (mobile or web). The server creates an ephemeral device token and starts a session, then returns a URL containing the token and session ID.

Prerequisites

• An API key with permission deeplink:write.

Session Initiation Flow

The session initiation includes three steps.

Step 1: Session trigger

A person triggers a session by performing a designated action within your app. Your app sends a request to your backend to initiate the process. The IDV SDK in your app is not yet involved at this stage.

Step 2: Get handoff URL

Your backend uses the API key to create a token and session.

Request

curl --location 'https://<IDV_HOST>/api/v1/deeplink?workflowId=<workflow_id>' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: ApiKey <apikey>' \
    --data '{
      "metadata": { "foo": "bar" },
      "locale": "ru-ru",
      "ttl": 3600
    }'

Parameter	Location	Type	Default value	Description
workflowId	query	string		Workflow that will be used to start a session.
metadata	payload	arbitrary object	{}	Metadata that will be attached to the created session.
locale	payload	string	null	Locale that will be used for a session.
ttl	payload	int	3600	Time-to-live for the session and returned token.

Response

{
  "url": "https://<IDV_HOST>/mobile?authorization=Token%20<token>&sessionId=<session_id>",
  "createdAt": "2025-12-30T10:55:33.949Z",
  "expiresAt": "2025-12-30T11:55:33.949Z",
  "workflowIds": ["<workflow_id_1>", "<workflow_id_2>"]
}

Field	Type	Description
url	string	Handoff URL.
createdAt	time string (ISO 8601 extended format)	Time when the token was created.
expiresAt	time string (ISO 8601 extended format)	Time when the token and session will expire.
workflowIds	list of strings	Workflows list passed in workflowId query param.

Handoff URL parameters

Parameter	Description
authorization	Handoff URL value in the format Token <ephemeral token>.
sessionId	ID of the started session.

Step 3: Hand off to client

Return the url from the response to your client application (mobile or web). The client opens the URL to continue the session.