Provisioning

Provisioning is how devices get registered in ThingsBoard with credentials before they start sending data. There are two independent approaches: Bulk Provisioning (an admin imports a CSV file) and Auto Provisioning (devices self-register on first boot). Both result in the device existing in ThingsBoard with credentials ready to use.

This is distinct from Claiming: provisioning creates the device and gives it credentials; claiming transfers an already-provisioned device to a specific customer.

Bulk provisioning imports a list of devices or assets into ThingsBoard from a CSV file in one operation. Each row creates (or updates) one entity and can include attributes, telemetry, and device credentials — no API scripting required.

A common use case is pre-loading a batch of devices before shipping so they can use Auto Provisioning with the Check Pre-Provisioned Devices strategy: the devices are known to ThingsBoard in advance and only those exact devices are allowed to self-register.

1. Navigate to Entities ⇾ Devices (or Assets) and click the Import icon.
2. Upload your CSV file. Set the delimiter and toggle First line contains column names if applicable.
3. Enable Update attributes/telemetry if you want matching existing entities to be updated rather than flagged as errors.
4. Map each CSV column to a ThingsBoard field type (Name, Type, attribute, telemetry, Access Token, etc.).
5. Review the results — the summary shows how many entities were created, updated, or failed.

The file must have at minimum a name column and a type column. All other columns are optional. Empty cells are allowed — missing values are simply skipped for that entity.

name,type,label,serialNumber,accessToken
Sensor-001,Temperature Sensor,Warehouse A,SN-4A21F,tok-a1b2c3d4
Sensor-002,Temperature Sensor,Warehouse B,SN-4A22F,tok-e5f6g7h8
Gateway-001,IoT Gateway,Main Hub,GW-0010A,tok-i9j0k1l2

For automated pipelines — CI/CD, ERP integrations, or manufacturing systems — the same import can be triggered programmatically. See Bulk Import REST API for the endpoint and request format.

Devices self-register on first boot by sending a provisioning request with a key and secret embedded in firmware. ThingsBoard validates it, creates or finds the device, and returns the credentials the device will use for all subsequent communication. No admin action needed per device.

Once provisioned, the device’s provisionState server-side attribute is set to provisioned. Re-sending a provisioning request after that will be rejected with a failure response — provisioning is a one-shot operation.

To re-provision a device, the reset procedure depends on the strategy:

Allow Creating New Devices — delete the device in ThingsBoard. The device can then provision again as a new entity.

Check Pre-Provisioned Devices — delete the provisionState server-side attribute on the device (device ⇾ Attributes ⇾ Server attributes). The device name and credentials remain intact. Via REST API: DELETE /api/plugins/telemetry/DEVICE/{deviceId}/SERVER_SCOPE?keys=provisionState

Allow creating new devices — ThingsBoard creates the device on first request. Use this when device names (e.g. MAC addresses) aren’t known at manufacturing time but are readable by firmware at runtime.

Check Pre-Provisioned Devices — ThingsBoard only accepts devices already present in the system and rejects all others. Use bulk provisioning to load the approved list first. Good for regulated or high-security deployments where unknown devices must be blocked.

X.509 Certificate Chain — instead of a key/secret pair, register one intermediate CA certificate on the profile. ThingsBoard authenticates each connecting device via mutual TLS against that certificate and extracts the device name from the leaf certificate’s Common Name using a configurable regular expression. Best for MQTT fleets that already issue device certificates from a shared certificate authority. See X.509 Certificate for how to generate the certificate hierarchy and connect a device.

In the Device Profile, go to the Device Provisioning tab and select a strategy.

For Allow Creating New Devices and Check Pre-Provisioned Devices, copy the generated Provision device key and Provision device secret — these go into the device firmware.

For X.509 Certificate Chain, there’s no key/secret pair. Instead:

How the credential type is determined depends on the strategy:

Allow Creating New Devices — the device specifies the type in the provision request body (credentialsType: ACCESS_TOKEN, MQTT_BASIC, or X509_CERTIFICATE). ThingsBoard creates the device with exactly those credentials.

Check Pre-Provisioned Devices — ThingsBoard returns whatever credentials are already configured on the device, regardless of what the provision request body contains. To use a specific credential type (for example, MQTT Basic), set it on the device before it provisions — via the device Credentials tab in the UI, or via POST /api/device-with-credentials for bulk setup. Values sent in the provision request body are ignored.

X.509 Certificate Chain — always X.509. There’s no separate choice: the device’s own certificate, signed by the profile’s registered CA, is the credential.

Provisioning requests can be sent over MQTT, HTTP, and CoAP. See the transport-specific guides for exact topics, endpoints, and complete request/response examples:

• MQTT Provisioning API — also supports X.509 certificate chain provisioning (v3.5+)
• HTTP Provisioning API — supports Access Token and MQTT Basic
• CoAP Provisioning API — supports Access Token