How to Link a Thing

Before getting the user's device data, there is a necessary a procedure called link thing, which allows the platform to know that the user is the owner of the thing.

In order to link a thing, the user must be logged in and the thing must be activated.

Our Platform provides two ways to associate a thing to an user's app:

• Link Thing with the thingToken.
• Link Thing with a shared id from the device.

Link Thing from an App with the thingToken

The easiest way to link a thing is when the user provides the thingToken to the app. The thingToken could be printed at the users' manual, or printed on a card inside the packaging or received after registering the thing at your product's web. There are many ways to do this.

Once the App gets the thingToken from the user, the App has to perform the next operation:

curl -i -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: {{SESSION TOKEN}}" \
  -d '{"thingToken": "{{thingToken}}"}' \
  -X POST "https://api.thethings.io/v2/me/things" -k

{
  "status": "success",
  "message": "linked",
  "thingId": "01234_567890-0abcde_fghi-jklm_nopqrs-tuvxyz"
}

At this point the App has access to the user's device data.

Link Thing with a shared id from the device

There are some use cases where the App can't know about the thingToken. For this scenario, the device and the app have to work together to proceed to link the device to the user's app.

This is solved creating a shared serial string/number. For example, if a thing like an scale creates a Wi-Fi network, you can use the Wi-Fi SSID to provide a serial string to the app (the app can check for the Wi-Fi networks until it recognizes a patron on a SSID).

In this scenario, both, the App and the device can start the linking process using this shared serial and wait for the other part to complete the link process. There is a limit of 24 hours to complete the process, if not this has to be restarted.

The App endpoint:

curl -i -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: { {SESSION TOKEN} }" \
  -d '{"linkId": "{ {serial} }"}' \
  -X POST "https://api.thethings.io/v2/me/things/link-id" -k

# If the thing hasn't done its link api call
{
  "status": "success",
  "message": "waiting for thing"
}

# If the thing has done its link api call
{
  "status": "success",
  "message": "linked",
  "thingId": "01234_567890-0abcde_fghi-jklm_nopqrs-tuvxyz"
}

The device endpoint:

curl -i -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"linkId": "{ {serial} }"}' \
  -X POST "https://api.thethings.io/v2/things/{ {thingToken} }/link-id" -k

# If the app hasn't done its link api call
{
  "status": "success",
  "message": "waiting for app"
}

# If the app has done its link api call
{
  "status": "success",
  "message": "linked",
  "thingId": "01234_567890-0abcde_fghi-jklm_nopqrs-tuvxyz"
}

How to Unlink a Thing (inverse operation)

If you want to remove the ownership of a thing from a user there is a necessary procedure called unlink thing (inverse to the previous link-thing), which allows the platform to know that the App user will no longer be able to access the device data.

In order to unlink the thing the user must be logged in and the thing must be activated and previously linked.

Unlink thing from an App with the thingId

The thingId could be retrieved from the GET:/me/things or GET:/me/resources.

curl -i -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: { {SESSION TOKEN} }" \
  -X DELETE "https://api.thethings.io/v2/me/things/{ { thingId } }" -k

{
  "status": "success",
  "message": "unlinked",
  "thingId": "01234_567890-0abcde_fghi-jklm_nopqrs-tuvxyz"
}

At this point the App no longer has access to the user's device data.