Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

API de revendication

Revendiquez des appareils sous licence dans votre organisation depuis un programme, lisez leur propriété et libérez-les, avec l'explication de chaque code de refus.

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 :

  1. L’appareil est connecté à Internet et sa connexion cloud est activée.
  2. 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.
  3. 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éthodeCheminPermissionAction
POST/api/iot/claimiot_provisioning.claimRevendiquer un appareil, ou le vérifier avec un essai à blanc
GET/api/iot/devices/{deviceId}/ownershipiot_provisioning.claimOrigine d’un appareil, son certificat et son réglage de libération
PATCH/api/iot/devices/{deviceId}/ownershipiot_provisioning.releaseAutoriser ou interdire la libération depuis la page propre de l’appareil
POST/api/iot/claim/release/{deviceId}iot_provisioning.releaseRendre 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

ChampRègle
serialObligatoire. De 6 à 32 lettres, chiffres et tirets ; la casse est sans importance
secretObligatoire. 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
nameFacultatif, de 1 à 128 caractères. Par défaut : le numéro de série
iotAssetIdFacultatif. Le site ou l’actif sur lequel placer l’appareil
dryRunFacultatif. 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

StatutstatusSignification
201claimedL’appareil vous appartient désormais
200claimed avec alreadyOwned: trueVotre organisation le possède déjà ; rien n’a changé
200claimableL’essai à blanc a réussi ; la réponse contient serial, model, type et hw
200in_progressUne revendication de cet appareil est en cours ; consultez la liste des appareils dans un instant

Autres champs d’une revendication :

ChampSignification
name, renamedLe nom de l’appareil. Si un appareil de ce nom existe, un numéro est ajouté (Pump house router (2)) et renamed vaut true
recreatedtrue lorsque votre organisation possédait l’appareil mais que sa fiche avait été supprimée ; elle a été recréée
placementUniquement 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.reasonStatutcodeMessageQue faire
not_claimable409CONFLICTCet 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_button409CONFLICTOuvrez 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_secret400VALIDATION_ERRORLe numéro de série ou le code de revendication n’est pas correct.Relisez le code sur la page Cloud
rate_limited429RATE_LIMIT_EXCEEDEDTrop de tentatives. Réessayez plus tard.Patientez ; voir les limites de tentatives ci-dessous
device_limit403FEATURE_NOT_AVAILABLELa 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é parLimite par heure
Numéro de série5 mauvais codes de revendication
Membre20 tentatives échouées (pour une clé : le titulaire de la clé)
Adresse appelante30 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é.

Statutdetails.reasonSignification
400confirm_mismatch« Saisissez exactement le numéro de série de l’appareil pour confirmer. »
404not_from_pool« Cet appareil n’a pas été ajouté depuis le pool d’usine. »
409still_referencedQuelque 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