This page is for integrators who add licensed routers, gateways and controllers to an organisation from their own tools, for example an installer app or a commissioning script. The steps in the app are on Adding and claiming devices; how claiming is protected is on Device identity and claiming security.
Paths are under https://<your host>/tenant/<tenantId>. Conventions are in REST API basics.
Before you call
A licensed device can be claimed only while someone is at it:
- The device is connected to the internet with its cloud connection on.
- Someone opens the claim window on the device’s own Cloud page. The window stays open for at most 15 minutes and closes after one successful claim.
- Your program sends the device’s serial and claim code while the window is open.
There is no route to open the claim window: it is opened on the device only.
Routes
| Method | Path | Permission | Does |
|---|---|---|---|
| POST | /api/iot/claim | iot_provisioning.claim | Claim a device, or check it with a dry run |
| GET | /api/iot/devices/{deviceId}/ownership | iot_provisioning.claim | Where a device came from, its certificate and release setting |
| PATCH | /api/iot/devices/{deviceId}/ownership | iot_provisioning.release | Allow or stop release from the device’s own page |
| POST | /api/iot/claim/release/{deviceId} | iot_provisioning.release | Release a device back to the factory pool |
All four are Admin permissions by default. Placing the claimed device on a site or asset in the same call also needs iot_asset.relations.manage on the key.
Claim a device
POST /api/iot/claim
| Field | Rule |
|---|---|
serial | Required. 6 to 32 letters, digits and dashes; case does not matter |
secret | Required. The 20-character claim code from the device’s Cloud page. Dashes, spaces and case are ignored; O is read as 0, I and L as 1 |
name | Optional, 1 to 128 characters. Default: the serial |
iotAssetId | Optional. The site or asset to place the device on |
dryRun | Optional. true checks everything and claims nothing |
The body is strict: an unknown field is a 400. The claim code is never sent back.
curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/claim' \
-H 'Authorization: Bearer sk_live_…' \
-H 'Content-Type: application/json' \
-d '{"serial":"RT420-2610-000123","secret":"7KQ2-M9XH-D4TB-6WRA-1NZC","name":"Pump house router","iotAssetId":"8d0e…"}'
{
"status": "claimed",
"serial": "RT420-2610-000123",
"deviceId": "6f1c…",
"model": "…",
"profileId": "a1b2…",
"name": "Pump house router",
"renamed": false,
"placement": "placed"
}
Answers
| Status | status | Meaning |
|---|---|---|
| 201 | claimed | The device is now yours |
| 200 | claimed with alreadyOwned: true | Your organisation already owns it; nothing changed |
| 200 | claimable | A dry run passed; the answer has serial, model, type and hw |
| 200 | in_progress | A claim of this device is running right now; read the device list in a moment |
Other fields of a claim:
| Field | Meaning |
|---|---|
name, renamed | The device’s name. If a device of that name exists, a number is added (Pump house router (2)) and renamed is true |
recreated | true when your organisation owned the device but its device record had been deleted; it was created again |
placement | Only when you sent iotAssetId: placed, not_permitted (the key lacks iot_asset.relations.manage), unavailable (sites and assets are off) or failed. The claim stands in every case |
A claimed device gets a copy of its model’s device profile and its factory certificate as its X.509 credential, and it reconnects into your organisation within seconds. A iot.device.claimed webhook event is sent (see Webhook event reference).
Refusals
Every refusal carries one of five codes in details.reason. Branch on it, not on the message.
details.reason | Status | code | Message | What to do |
|---|---|---|---|---|
not_claimable | 409 | CONFLICT | This device cannot be added. Check the serial; if it is right, the device belongs to another account: ask the seller to release it. | Check the serial. An unknown serial, a retired device and a device of another organisation all answer this; the owner is never named |
press_claim_button | 409 | CONFLICT | Open the claim window on the device’s Cloud page (it stays open for 15 minutes), then try again. | Open the window on the device and retry |
bad_secret | 400 | VALIDATION_ERROR | The serial or claim code is not correct. | Read the code again from the Cloud page |
rate_limited | 429 | RATE_LIMIT_EXCEEDED | Too many attempts. Try again later. | Wait; see the attempt limits below |
device_limit | 403 | FEATURE_NOT_AVAILABLE | The device limit of this account is reached. | Remove a device or change the plan |
While the claim window is closed, the claim code is not checked at all, so a closed window never tells whether a code was right. The device limit is checked last, before anything is created.
Attempt limits
Failed attempts (an unknown serial, a closed claim window, a wrong code) are counted over a sliding hour. When one of these is full, the attempts it covers answer rate_limited:
| Counted per | Limit per hour |
|---|---|
| Serial | 5 wrong claim codes |
| Member | 20 failed attempts (for a key: the key’s holder) |
| Calling address | 30 failed attempts |
A dry run runs the same checks, and a failed dry run counts like a failed claim. Do not test codes in a loop: five wrong codes lock the serial for the hour.
Ownership
GET /api/iot/devices/{deviceId}/ownership answers { ownership, capabilities }. For a claimed device ownership has fromPool: true, serial, model, claimedAt, claimedByUserId, certificate (status, notAfter), allowDeviceRelease and blockers (what still refers to the device). A device created in your organisation answers fromPool: false. The claimer’s name (claimedBy) needs a member permission that keys never hold, so a key gets only the id.
PATCH with { "allowDeviceRelease": false } stops anyone from releasing the device with the button on its own Cloud page. The default is true.
Release a device
POST /api/iot/claim/release/{deviceId} with { "confirmSerial": "RT420-2610-000123", "reason": "Returned to supplier" } (reason up to 500 characters) sends the device back to the factory pool. The answer is 200 { serial, unitStatus, certificateKept }. Its data stays in your organisation; the next owner must be at the device to claim it. A iot.device.released webhook event is sent.
| Status | details.reason | Meaning |
|---|---|---|
| 400 | confirm_mismatch | “Type the device serial exactly to confirm.” |
| 404 | not_from_pool | “This device was not added from the factory pool.” |
| 409 | still_referenced | Something still refers to the device, for example a site or asset it is placed on; details.moduleId and details.count say what. Remove that first |

