Provisioning

The MQTT Provisioning API lets a device register itself with ThingsBoard on first boot — before it has any credentials. See Provisioning for the full workflow and how to configure the device profile.

For general MQTT connection setup (host, port, TLS, credential types) see Getting Connected. Provisioning uses a special username and its own topics:

Subscribe to /provision/response before publishing the request so you don’t miss the reply.

All strategies share three required fields:

ThingsBoard creates the device and generates an access token automatically. Use this when the device has no pre-assigned credentials.

Request:

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "PUT_PROVISION_KEY_HERE",
  "provisionDeviceSecret": "PUT_PROVISION_SECRET_HERE"
}

Response:

{
  "status": "SUCCESS",
  "credentialsType": "ACCESS_TOKEN",
  "credentialsValue": "sLzc0gDAZPkGMzFVTyUY"
}

Use credentialsValue as the MQTT username for all subsequent connections.

The device supplies its own access token. ThingsBoard registers the device with that token.

Request:

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "PUT_PROVISION_KEY_HERE",
  "provisionDeviceSecret": "PUT_PROVISION_SECRET_HERE",
  "credentialsType": "ACCESS_TOKEN",
  "token": "DEVICE_ACCESS_TOKEN"
}

Response:

{
  "status": "SUCCESS",
  "credentialsType": "ACCESS_TOKEN",
  "credentialsValue": "DEVICE_ACCESS_TOKEN"
}

The device supplies its own clientId, username, and password. All three are optional — include only the fields your firmware uses.

Request:

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "PUT_PROVISION_KEY_HERE",
  "provisionDeviceSecret": "PUT_PROVISION_SECRET_HERE",
  "credentialsType": "MQTT_BASIC",
  "clientId": "DEVICE_CLIENT_ID_HERE",
  "username": "DEVICE_USERNAME_HERE",
  "password": "DEVICE_PASSWORD_HERE"
}

Response:

{
  "status": "SUCCESS",
  "credentialsType": "MQTT_BASIC",
  "credentialsValue": {
    "clientId": "DEVICE_CLIENT_ID_HERE",
    "userName": "DEVICE_USERNAME_HERE",
    "password": "DEVICE_PASSWORD_HERE"
  }
}

The device generates a key pair, sends the public certificate hash, and ThingsBoard registers the certificate. The provisioning connection itself must use MQTT over TLS (port 8883).

Request:

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "PUT_PROVISION_KEY_HERE",
  "provisionDeviceSecret": "PUT_PROVISION_SECRET_HERE",
  "credentialsType": "X509_CERTIFICATE",
  "hash": "MIIB........AQAB"
}

hash is the PEM-encoded public certificate (the full cert string, not just the fingerprint).

Response:

{
  "status": "SUCCESS",
  "credentialsType": "X509_CERTIFICATE",
  "credentialsValue": "MIIB........AQAB",
  "credentialsId": "f307a1f717a12b32c27203cf77728d305d29f64694a8311be921070dd1259b3a"
}

Subscribe to the response:

Start the subscription client to receive the credentials from ThingsBoard:

mosquitto_sub -d -q 1 -h "$THINGSBOARD_HOST" -p 1883 -t "/provision/response" -u "provision"

Send the provisioning request:

Send request with the provisioning data from your device profile:

mosquitto_pub -d -q 1 -h "$THINGSBOARD_HOST" -p 1883 -t "/provision/request" -u "provision" -m '{"deviceName": "DEVICE_NAME", "provisionDeviceKey": "PUT_PROVISION_KEY_HERE", "provisionDeviceSecret": "PUT_PROVISION_SECRET_HERE"}'

If provisioning fails, ThingsBoard returns:

{
  "status": "FAILURE",
  "errorMsg": "Provision request is not found!"
}

Common causes: wrong provisionDeviceKey/provisionDeviceSecret, provisioning disabled in the device profile, or device name already registered with different credentials.