Claiming

Device claiming transfers a device from the tenant’s account to a specific customer. A manufacturer ships thousands of devices pre-provisioned under the tenant — then each end customer claims their own unit using a secret key. Once claimed, only that customer’s users can see the device and its data.

There are two scenarios depending on what the device can do. Both end the same way: the customer opens the Claim Device widget, enters the device name and secret key, and ownership transfers.

Use this when the device has a display, button, or indicator and can show the customer a code at setup time — for example, a Wi-Fi thermostat that shows a PIN on its screen during first boot, or a smart meter with a QR code generated on demand. The device generates a secret key on a trigger and publishes it to ThingsBoard; the customer reads it directly off the device and claims it.

Claiming must be enabled before a device can publish claiming data. Choose one:

• Globally — set SECURITY_CLAIM_ALLOW_CLAIMING_BY_DEFAULT=true
• Per device — add a server-side attribute claimingAllowed = true on the device

The device sends the following payload over any supported transport (MQTT, HTTP, CoAP):

{
  "secretKey": "your-secret",
  "durationMs": 60000
}

• secretKey — the secret customers must provide. Omit to use an empty string.
• durationMs — how long the key is valid (milliseconds). Omit to use the system default (SECURITY_CLAIM_DURATION). Maximum is 24 hours.

ThingsBoard stores the key and records its expiry in the device’s expirationTime server attribute.

The customer uses the Claim Device widget (or the REST API below), entering the device name and the secret key shown on the device.

Use this when the device has no UI at all — NB-IoT sensors, LoRaWAN trackers, or any device auto-provisioned via Platform Integrations that the customer never physically interacts with. The tenant generates secrets in advance and includes them in the product packaging, a welcome email, or a customer portal; the customer never touches the device to get the code.

For each device, set a server-side attribute named claimingData:

{
  "secretKey": "your-secret",
  "expirationTime": 1735689600000
}

• secretKey — the secret to distribute to the customer.
• expirationTime — Unix timestamp in milliseconds after which claiming is no longer allowed.

This can be done via the UI (Device → Attributes → Add) or in bulk via the REST API.

Send the device name and secret key to the customer through any external channel. The customer will need both to complete claiming.

Same as device-side: the customer uses the Claim Device widget or calls the REST API.

Customers can claim a device programmatically:

POST /api/customer/device/{deviceName}/claim
Content-Type: application/json

{"secretKey": "your-secret"}

On success the device is assigned to the requesting customer’s account.

To return a device to the tenant (remove customer ownership):

DELETE /api/customer/device/{deviceName}/claim

After reclaiming, the claimingAllowed attribute is removed (when SECURITY_CLAIM_ALLOW_CLAIMING_BY_DEFAULT is false), so the device cannot be claimed again until it is re-enabled.