Skip to content

Token URL

This authentication method is used when you choose to start a session via the server side, as opposed to starting a session directly from the device. See Starting a Session for details.

This process involves the use of a concept called an ephemeral token — a short-lived entity that allows you to collect data from the person and submit it to the platform, but does not allow access to any data other than what has been submitted with the ephemeral token itself. Once the token expires, it is destroyed and can no longer be used.

To proceed, you first need to create an API key with the Ephemeral devices permissions.

Prerequisites

  • API credentials: An API key with the permission Ephemeral Devices:Write issued and stored securely on your backend.

Session Initiation Flow

The session initiation includes five steps.

Token URL session initiation flow

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 the token

Your backend uses the API key to create a token.

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 token received in the previous step, your backend initiates a session for a specific workflow. At this step, you can pass metadata into the session from your backend.

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 URL:

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

Step 5: Token-based authentication

The application receives the token URL and uses it to continue the session.