Cette page s’adresse aux intégrateurs qui ajoutent des routeurs, passerelles et contrôleurs sous licence à une organisation depuis leurs propres outils, par exemple une application d’installation ou un script de mise en service. Les étapes dans l’application sont décrites dans Adding and claiming devices ; la manière dont la revendication est protégée est décrite dans Device identity and claiming security.
Les chemins se trouvent sous https://<your host>/tenant/<tenantId>. Les conventions sont décrites dans REST API basics.
Avant d’appeler l’API
Un appareil sous licence ne peut être revendiqué que lorsqu’une personne se trouve auprès de lui :
- L’appareil est connecté à Internet et sa connexion cloud est activée.
- Une personne ouvre la fenêtre de revendication sur la page Cloud de l’appareil. La fenêtre reste ouverte 15 minutes au maximum et se ferme après une revendication réussie.
- Votre programme envoie le numéro de série et le code de revendication de l’appareil pendant que la fenêtre est ouverte.
Il n’existe aucune route pour ouvrir la fenêtre de revendication : elle s’ouvre uniquement sur l’appareil.
Routes
| Méthode | Chemin | Permission | Action |
|---|---|---|---|
| POST | /api/iot/claim | iot_provisioning.claim | Revendiquer un appareil, ou le vérifier avec un essai à blanc |
| GET | /api/iot/devices/{deviceId}/ownership | iot_provisioning.claim | Origine d’un appareil, son certificat et son réglage de libération |
| PATCH | /api/iot/devices/{deviceId}/ownership | iot_provisioning.release | Autoriser ou interdire la libération depuis la page propre de l’appareil |
| POST | /api/iot/claim/release/{deviceId} | iot_provisioning.release | Rendre un appareil au pool d’usine |
Ces quatre permissions sont des permissions Admin par défaut. Placer l’appareil revendiqué sur un site ou un actif dans le même appel nécessite aussi iot_asset.relations.manage sur la clé.
Revendiquer un appareil
POST /api/iot/claim
| Champ | Règle |
|---|---|
serial | Obligatoire. De 6 à 32 lettres, chiffres et tirets ; la casse est sans importance |
secret | Obligatoire. Le code de revendication de 20 caractères de la page Cloud de l’appareil. Les tirets, espaces et la casse sont ignorés ; O est lu comme 0, et I et L comme 1 |
name | Facultatif, de 1 à 128 caractères. Par défaut : le numéro de série |
iotAssetId | Facultatif. Le site ou l’actif sur lequel placer l’appareil |
dryRun | Facultatif. true vérifie tout et ne revendique rien |
Le corps est strict : un champ inconnu entraîne une erreur 400. Le code de revendication n’est jamais renvoyé.
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"
}
Réponses
| Statut | status | Signification |
|---|---|---|
| 201 | claimed | L’appareil vous appartient désormais |
| 200 | claimed avec alreadyOwned: true | Votre organisation le possède déjà ; rien n’a changé |
| 200 | claimable | L’essai à blanc a réussi ; la réponse contient serial, model, type et hw |
| 200 | in_progress | Une revendication de cet appareil est en cours ; consultez la liste des appareils dans un instant |
Autres champs d’une revendication :
| Champ | Signification |
|---|---|
name, renamed | Le nom de l’appareil. Si un appareil de ce nom existe, un numéro est ajouté (Pump house router (2)) et renamed vaut true |
recreated | true lorsque votre organisation possédait l’appareil mais que sa fiche avait été supprimée ; elle a été recréée |
placement | Uniquement si vous avez envoyé iotAssetId : placed, not_permitted (la clé n’a pas iot_asset.relations.manage), unavailable (les sites et actifs sont désactivés) ou failed. La revendication reste valide dans tous les cas |
Un appareil revendiqué reçoit une copie du profil d’appareil de son modèle et son certificat d’usine comme identifiant X.509, puis se reconnecte à votre organisation en quelques secondes. Un événement webhook iot.device.claimed est envoyé (voir Webhook event reference).
Refus
Chaque refus porte l’un des cinq codes de details.reason. Traitez-le par code, pas par message.
details.reason | Statut | code | Message | Que faire |
|---|---|---|---|---|
not_claimable | 409 | CONFLICT | Cet appareil ne peut pas être ajouté. Vérifiez le numéro de série ; s’il est correct, l’appareil appartient à un autre compte : demandez au vendeur de le libérer. | Vérifiez le numéro de série. Un numéro inconnu, un appareil retiré et un appareil d’une autre organisation renvoient tous cette réponse ; le propriétaire n’est jamais nommé |
press_claim_button | 409 | CONFLICT | Ouvrez la fenêtre de revendication sur la page Cloud de l’appareil (elle reste ouverte 15 minutes), puis réessayez. | Ouvrez la fenêtre sur l’appareil et réessayez |
bad_secret | 400 | VALIDATION_ERROR | Le numéro de série ou le code de revendication n’est pas correct. | Relisez le code sur la page Cloud |
rate_limited | 429 | RATE_LIMIT_EXCEEDED | Trop de tentatives. Réessayez plus tard. | Patientez ; voir les limites de tentatives ci-dessous |
device_limit | 403 | FEATURE_NOT_AVAILABLE | La limite d’appareils de ce compte est atteinte. | Retirez un appareil ou changez de forfait |
Lorsque la fenêtre de revendication est fermée, le code de revendication n’est pas vérifié du tout ; une fenêtre fermée ne permet donc jamais de savoir si un code était juste. La limite d’appareils est vérifiée en dernier, juste avant toute création.
Limites de tentatives
Les tentatives échouées (numéro de série inconnu, fenêtre de revendication fermée, mauvais code) sont comptées sur une heure glissante. Lorsque l’une de ces limites est atteinte, les tentatives concernées renvoient rate_limited :
| Compté par | Limite par heure |
|---|---|
| Numéro de série | 5 mauvais codes de revendication |
| Membre | 20 tentatives échouées (pour une clé : le titulaire de la clé) |
| Adresse appelante | 30 tentatives échouées |
Un essai à blanc applique les mêmes contrôles, et un essai à blanc échoué compte comme une revendication échouée. Ne testez pas des codes en boucle : cinq mauvais codes verrouillent le numéro de série pendant une heure.
Propriété
GET /api/iot/devices/{deviceId}/ownership renvoie { ownership, capabilities }. Pour un appareil revendiqué, ownership contient fromPool: true, serial, model, claimedAt, claimedByUserId, certificate (status, notAfter), allowDeviceRelease et blockers (ce qui fait encore référence à l’appareil). Un appareil créé dans votre organisation renvoie fromPool: false. Le nom du revendicateur (claimedBy) exige une permission de membre que les clés n’ont jamais ; une clé n’obtient donc que l’identifiant.
PATCH avec { "allowDeviceRelease": false } empêche quiconque de libérer l’appareil avec le bouton de sa propre page Cloud. La valeur par défaut est true.
Libérer un appareil
POST /api/iot/claim/release/{deviceId} avec { "confirmSerial": "RT420-2610-000123", "reason": "Returned to supplier" } (reason jusqu’à 500 caractères) renvoie l’appareil au pool d’usine. La réponse est 200 { serial, unitStatus, certificateKept }. Ses données restent dans votre organisation ; le prochain propriétaire doit se trouver auprès de l’appareil pour le revendiquer. Un événement webhook iot.device.released est envoyé.
| Statut | details.reason | Signification |
|---|---|---|
| 400 | confirm_mismatch | « Saisissez exactement le numéro de série de l’appareil pour confirmer. » |
| 404 | not_from_pool | « Cet appareil n’a pas été ajouté depuis le pool d’usine. » |
| 409 | still_referenced | Quelque chose fait encore référence à l’appareil, par exemple un site ou un actif sur lequel il est placé ; details.moduleId et details.count indiquent quoi. Supprimez-le d’abord |

