New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Claim API

Claim licensed devices into your organisation from a program, read their ownership and release them, with every refusal code explained.

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:

  1. The device is connected to the internet with its cloud connection on.
  2. 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.
  3. 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

MethodPathPermissionDoes
POST/api/iot/claimiot_provisioning.claimClaim a device, or check it with a dry run
GET/api/iot/devices/{deviceId}/ownershipiot_provisioning.claimWhere a device came from, its certificate and release setting
PATCH/api/iot/devices/{deviceId}/ownershipiot_provisioning.releaseAllow or stop release from the device’s own page
POST/api/iot/claim/release/{deviceId}iot_provisioning.releaseRelease 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

FieldRule
serialRequired. 6 to 32 letters, digits and dashes; case does not matter
secretRequired. 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
nameOptional, 1 to 128 characters. Default: the serial
iotAssetIdOptional. The site or asset to place the device on
dryRunOptional. 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

StatusstatusMeaning
201claimedThe device is now yours
200claimed with alreadyOwned: trueYour organisation already owns it; nothing changed
200claimableA dry run passed; the answer has serial, model, type and hw
200in_progressA claim of this device is running right now; read the device list in a moment

Other fields of a claim:

FieldMeaning
name, renamedThe device’s name. If a device of that name exists, a number is added (Pump house router (2)) and renamed is true
recreatedtrue when your organisation owned the device but its device record had been deleted; it was created again
placementOnly 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.reasonStatuscodeMessageWhat to do
not_claimable409CONFLICTThis 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_button409CONFLICTOpen 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_secret400VALIDATION_ERRORThe serial or claim code is not correct.Read the code again from the Cloud page
rate_limited429RATE_LIMIT_EXCEEDEDToo many attempts. Try again later.Wait; see the attempt limits below
device_limit403FEATURE_NOT_AVAILABLEThe 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 perLimit per hour
Serial5 wrong claim codes
Member20 failed attempts (for a key: the key’s holder)
Calling address30 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.

Statusdetails.reasonMeaning
400confirm_mismatch“Type the device serial exactly to confirm.”
404not_from_pool“This device was not added from the factory pool.”
409still_referencedSomething 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