Claim ownership of a device

To enable a device to send data via the Tracking API and store it in the Tracking backend, the device needs to be claimed by an end user. Unclaimed devices cannot communicate with the Tracking API.

In the Tracking API, an end user who claimed a device, is referred to as the device owner. The device owner controls the device and can access data ingested by it to the Tracking API.

NOTE: The device owner is a different from the device vendor, who is responsible for provisioning a device license.

Claim a device to a project

Prerequisites:

• A valid Device License of a device that has not been claimed yet
• A valid HERE account user (who is also a member of a Tracking project)

Log the user in

curl -X POST \
  https://tracking.api.here.com/users/v2/login \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "{userEmail}",
    "password": "{userPassword}"
}'

This will return a user access token: accessToken.

Add the device to the user project

Send the request below to the registry endpoint. If the user is a member of multiple projects, the target project ID needs to be specified in the projectId query parameter (note that this is different from the projectAppId).

NOTE: One only needs deviceId, but not deviceSecret for claiming a device.

curl -X PUT \
  https://tracking.api.here.com/registry/v2/devices/{deviceId}?projectId=`projectId` \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json'

This will return a newly created trackingId. This is a unique identifier associated with the device data in the Tracking backend.

NOTE: trackingId is different from the deviceId used in the license. The deviceId is permanently associated with the hardware, and the trackingId is associated with the device data. If the device is later sold or transferred, the deviceId remains the same but the trackingId changes when the device is reclaimed. This way the new owner cannot access the old data.

Verify the device is in the user's list of devices

Send a GET request to the users endpoint. If the user is a member of multiple projects, the target project ID needs to be specified in the projectId query parameter.

curl -X GET \
  https://tracking.api.here.com/users/v2/devices?projectId=`projectId` \
  -H 'Authorization: Bearer {accessToken}'

This will list all the devices claimed by a user project identified by the projectId.