Device Whitelist


Device whitelist service provides an extra layer of security when devices bootstrap in your account.

In order to claim ownership of a device and enable certain features and/or authorizations on a device at the time of bootstrap, a "Device Profile" is needed. To claim the device ownership, you have to generate a "DeviceProfileUID" and write it in the u-blox module using the proper AT command; you can do it a) remotely or b) during the production of your device. When the device bootstraps,  the associated features and authorizations are provisioned on the device and the device is added to your account (see Getting started guide)

To avoid the misuse of your device profile by a malicious user you can use the whitelist functionality and enable the automatic feature provisioning only to those devices that have been registered in the whitelist.  

How whitelist works

Using the whitelist APIs or the Thingstream portal UI, you can add the device identifier  RoTPublicUIDs  to the list of devices allowed to complete the bootstrap and provisioning process.

When a device bootstraps in your domain, it is first checked against the whitelist:

When a new device profile is created using the UI, the whitelist option is active by default for security reason. If you bootstrap a device without adding it in the whitelist, the device goes in the blacklist and you can unblock it only using the User Interface, as explained in a later section.

There is, however, the possibility of turning off the whitelist option: at the time of creating a device profile, you can select to "ignore" whitelist when a device bootstraps. You can do it at later stage as well modifying the device profile in the UI. Just remind that turning of the whitelist check on an existing device profile, affects only the devices that bootstrap after the moment of the change.  

Get the RoTPublicUID  module identifier

Each module has a unique and immutable identifier protected by the Root of Trust. 

To know the RoTPublicUID of a device you can use the following AT command

You can retrieve the RoTPublicUID of each device during production line and add it it to your whitelist immediately using the API or off-line using UI or API as clarified in the following section.

Whitelist configuration

Using Thingstream portal

To add one or more devices to the whitelist, signup to your Thingstream account and select the Security Services section from the left side menu. From the sub-menu you can enter in the whitelist section and add devices by using the Manage button. You can add single devices or upload a csv file.

Using API

There are two ways you can add devices in whitelist using API:

You can also get a list of all devices added in whitelist. In addition, you can use APIa to exclusively get :

Note: once the device has completed the bootstrap (including the provisioning of the features) you can remove the RoTPublicUID from the Whitelist without any impact on the device. The removal of the item from the whitelist does not trigger the deletion of the thing in the Thing list section.


Add devices using an array of RoTs

If you need to add few devices to the whitelist or automat the process you can use the API providing in input a list of RoTPublicUIDs as in the exmple

curl --location --request POST '' \

--header 'Content-Type: application/json' \

--header 'Authorization: [Bearer Token]' \

--data-raw '{

    "RoTPublicUIDs": ["fff0008003fa615"],

    "Action": "ADD"


Add a device using a csv file

If you wish to upload data using CSV, please consider that:



TYPE is the type of ID provided above. For now  the only possible value is:


but in the future other types of identifiers could be supported

This is an example that you can use

curl --location --request POST '' \

--header 'Content-Type: application/octet-stream' \

--header 'Authorization: [Bearer Token]' \

--data-raw 'Id,Type,Action\r\n0002000089282256,ROTPublicUID,ADD\r\n\r\n'

Get list of blacklisted devices

Any device that bootstrap in your account and it has not been added to the whitelist,  will be blacklisted and no action is possible for this device until it is activated through the UI.

To get the list of devices in the balcklist use the following API

curl --location --request POST '' \

--header 'Content-Type: application/json' \

--header 'Authorization: [Bearer Token]' \

--data-raw '{"Filter": "BLACKLISTED"}'

To activate a blacklisted device, you need to access to your account in the Thingstream portal  and activate the device as explained in the following section

Activate a blacklisted device

To see the devices in the blacklist, login to your Thingstream account and select the Security Services section from the left side menu. From the sub-menu you can enter in the Blacklist section and see the list of blocked devices. To activate a thing

Once the thing has been activated the corresponding RoTPublicUID is added to the whitelist and  the platform triggers the automatic provisioning in the device of the features defined in the device profile (that has been sealed in the device) at the moment of the activation. 

Provisioning will happen at the next security heartbeat.