Activations API

Use Activations API to create and manage activation codes and provide easier and uniform device rollouts to your field engineers, customers or end users.

With activation codes your field engineers can do a hassle-free device rollout without having in-depth knowledge of device types and network specification.

To read more about available partner services, go to Get started for Partners.

Pre-provision devices on a network of your choice (you need your own account on the network service)
Use device type and network details to generate an activation code
Give an end-user the activation code to rollout their device

Generating an activation code

Hardware ID

Hardware ID uniquely identifies the device chipset within your internal reference system, e.g. MAC address, Device EUI or IMSI number. One Hardware ID maps to exactly one activation code.

When an end-user rolls out a device, this field will become the name of the device.

Hardware ID could be used to troubleshoot activations. E.g. when end-user asks for support during rollout, partner might ask for Hardware ID to lookup for the device.

Carefully choose your Hardware IDs:

Example: LoRa devices
Choose Device EUIs as Hardware ID
Example: NB-IOT devices
Choose IMEI or IMSI as Hardware ID

Options

You can configure the activation to allow different rollout options in regards to desired device type or a network. For example, if you have a multi-network hardware device and you want to allow users to choose their preferred network, you can define multiple options. Each option will describe network-specific keys needed for proper provisioning.

Single option: a device type using a connectivity
Multiple options:
- a device type using multiple connectivities
- multiple device types using multiple connectivities

Description

Use option description field to show more information of the option to your end-user during the rollout phase. For example, you can explain in more detail why this option is more suitable than other ones, whether there are additional subscription fees, or just a generic text describing the device type and network included in this option - “Gizmo device on the Orange NB-IoT network”. You are also free to leave it empty.

Device type

Choose from a published device type version. If none, you can create and publish a new device type.
You can define multiple device types in different activation options.

Choose an existing device type, e.g. iotmate/counter

Network

These are the networks that are supported so far:

The Things Network - thethingsnetwork
Loriot - loriot
Actility ThingPark - thingpark
Proximus MyThings - mythings
Lattelecom - lattelecom
Things Connected - tc
T-Mobile NL - tmobilenl
Orange BE - orangebe

Data

For LoRa networks you need to provide a corresponding devEui field.
For thethingsnetwork LoRa network specifically, you need to provide both devEui and applicationId.
For tmobilenl you need to provide IMEI and IMSI.
For orangebe you should leave data field empty, e.g "data": {}.

Example: Create an activation for counter device on Loriot network

curl -X POST \
  https://api.allthingstalk.io/partner/iotmate/activations \
  -H 'Authorization: Bearer <Partner Token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Draft activation",
  "hardware": {
    "id": "cnt-0001"
  },
  "options": [
    {
      "description": "Counter device on the 'Loriot' network",
      "device": {
        "type": "iotmate/counter"
      },
      "network": {
        "networkId": "loriot",
        "data": {
          "devEui": "1020304050607080"
        }
      }
    }
  ]
}'

Response: 201 Created

{
  "code": "LSPAPNRU",
  "description": "Draft activation",
  "status": "unused",
  "activatedDeviceId": null,
  "activatedOptionId": null,
  "hardware": {
      "id": "cnt-0007"
  },
  "options": [
    {
      "id": "UYPNLJOG",
      "description": "Counter device on the 'Loriot' network",
      "device": {
        "type": "iotmate/counter:latest"
      },
      "network": {
        "networkId": "loriot",
        "data": {
          "activationMethod": "abp",
          "devEui": "1020304050607080",
          "appEui": null,
          "devAddr": null,
          "gatewayEui": null,
          "appSKey": null,
          "nwkSKey": null
        }
      }
    }
  ]
}

Rolling out a device using activation code

If you want to develop your own web or mobile app to rollout devices, we offer you an API for that.
To do a successful call, you need:

Code

Activation code generated when creating activation.

Option ID

Option code is also generated. It holds info about chosen device type and network.

Ground ID

Choose a ground in which you want to rollout the device.

Example: Activate a counter device

curl -X POST \
  https://api.allthingstalk.io/activate \
  -H 'Authorization: Bearer <User Token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "IDZJWWFU",
  "option": "ZFUOWCQD",
  "groundId": "YTwUyGVSMa5A66HGFHsBrMjP"
}'

For detailed API usage, read Activations API Reference →

In this article