Skip to main content
Some journeys require end users to interact directly from their own device, such as capturing a selfie, scanning a document, or completing biometric verification. The device connection flow allows you to securely connect an end user’s device (mobile or desktop) to an active journey instance. This guide explains how to generate a connect token and exchange it for an end-user token that enables the device to complete tasks.

​
When to use device connection

Use this flow when:
  • The journey includes tasks that require device-specific capabilities such as camera and biometrics.
  • You want end users to complete verification steps on their own mobile device.
  • Your integration involves a handoff between a backend system and a user-facing application.

​
How it works

The device connection flow involves two API calls:
  • Create a connect token: Your backend calls /journey/device/start to generate a short-lived connect token.
  • Exchange for end-user token: The end user’s device calls /journey/device/connect with the connect token to receive an end-user token.

​
Prerequisites

Before connecting a device, you need:
  • An active journey instance: You must have already started a journey and have the instanceId
  • Access token: A valid access token from the Authenticate step

​
Step 1: Create a connect token

Call the /journey/device/start endpoint from your backend to generate a connect token.
cURL
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/captain/api/journey/device/start \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "PiIuACmx8Q8R7qPnAkLAqBAT",
    "scope": ["mobile"]
  }'

​
Response

The response contains the connect token:
JSON
{
  "connectToken": "FtKXWJ7dQ6HTEDa9ScPWzNKY0kHoG_wA",
  "tokenType": "connect",
  "expiresIn": "120",
  "scope": ["mobile"]
}
The connect token expires quickly, typically 120 seconds. Generate it only when the end user is ready to connect their device.

​
Step 2: Pass the token to the end user

After receiving the connect token, pass it to the end user’s device. Common methods include:
  • QR code: Display a QR code containing the token or a URL with the token.
  • Deep link: Send a link that opens your mobile app with the token.
  • SMS/Email: Send the token or a connection URL directly to the user.

​
Step 3: Connect the end user device

From the end user’s device, call /journey/device/connect to exchange the connect token for an end-user token.
cURL
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/captain/api/journey/device/connect \
  --header 'Authorization: Bearer FtKXWJ7dQ6HTEDa9ScPWzNKY0kHoG_wA' \
  --header 'Content-Type: application/json' \
  --data '{
    "deviceInfo": {
      "deviceId": "exampleDeviceId123",
      "deviceName": "deviceName",
      "deviceType": "deviceType"
    },
    "connectToken": "FtKXWJ7dQ6HTEDa9ScPWzNKY0kHoG_wA"
  }'
The connect token obtained from the /journey/device/start endpoint must also be used as the Bearer token in the Authorization header for the /journey/device/connect request.

​
Response

The response contains the end-user token:
JSON
{
  "endUserToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8.eyJqdGkiOiJsRzlsZnZTVFVrcGNTTkVmSWx3amZXT1JRMkJwZEhGcCIsInNjb3BlIjpbImRlbW8zNCIsImF1dGgiXSwiaWF0IjoxNzEyMDc1OTMwLCJleHAiOjE3MTIwNzk1MzAsImF1ZCI6InVzLWVhc3QtMS5nYmdnby5jb20vI2RldmljZSJ9.Adn32WkNlhAlyFyHLH9EEVvFHk-FIhQn9Wiphb_BTRI",
  "tokenType": "end-user",
  "expiresIn": 3600
}

​
Step 4: Use the end-user token

The end-user token is a JWT that the device uses to authenticate subsequent API calls. Include it in the Authorization header when completing tasks:
cURL
curl --request POST \
  --url https://eu.platform.go.gbgplc.com/captain/api/journey/task/update \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8.eyJqdGkiOiJsRzlsZnZTVFVrcGNTTkVmSWx3amZXT1JRMkJwZEhGcCIsInNjb3BlIjpbImRlbW8zNCIsImF1dGgiXSwiaWF0IjoxNzEyMDc1OTMwLCJleHAiOjE3MTIwNzk1MzAsImF1ZCI6InVzLWVhc3QtMS5nYmdnby5jb20vI2RldmljZSJ9.Adn32WkNlhAlyFyHLH9EEVvFHk-FIhQn9Wiphb_BTRI' \
  --header 'Content-Type: application/json' \
  --data '{
    "intent": "Complete",
    "instanceId": "PiIuACmx8Q8R7qPnAkLAqBAT",
    "taskId": "TkoviRO58Q8R7qPnAkLAqBAT",
    "context": { ... }
  }'
If you need to connect a different device to the same journey instance, you must generate a new connect token by calling /journey/device/start again with the same instanceId. Each call generates a unique connect token.

​
Error handling

Common error codes when connecting an end user device, their causes, and solutions:
Error codeCauseSolution
400Connect token already used.The connect token has already been used and deleted. Generate a new connect token.
401Connect token expired or invalid.Generate a new connect token.
403Device type not allowed by scope.Check the scope parameter when creating the connect token.
404Journey instance not found.Verify the instanceId is correct and the journey is still active.
The connect token can only be used once. After a device successfully exchanges the connect token for an end-user token, the connect token is immediately invalidated and deleted from the system.If another device, or the same device attempts to use the same connect token again, then the API returns an error because the token no longer exists.What happens when a different device tries to connect using an already-used token:
  1. Device A uses the connect token and successfully receives an end-user token.
  2. The connect token is deleted from the system.
  3. Device B tries to use the same connect token.
  4. The API returns an error because the token no longer exists.

​
API reference