API des appareils et des profils

Ces routes gèrent les appareils et les profils d’appareils par code. Les chemins se trouvent sous https://<votre hôte>/tenant/<tenantId>. Les conventions (pagination, corps stricts, heures) sont décrites dans REST API basics.

Appareils

Lister les appareils

GET /api/iot/devices (pages à partir de 1)

{
  "devices": [
    {
      "deviceId": "6f1c…",
      "name": "pump-station-04",
      "label": "Pump station 4",
      "type": "pump-controller",
      "serial": null,
      "deviceProfileId": "a1b2…",
      "status": "ACTIVE",
      "isGateway": false,
      "gatewayDeviceId": null,
      "model": null,
      "fwTitle": null,
      "fwVersion": null,
      "online": true,
      "active": true,
      "lastConnectAt": "2026-11-08T06:12:03.000Z",
      "lastDisconnectAt": null,
      "lastActivityAt": "2026-11-09T09:41:10.000Z",
      "lastRemoteIp": "203.0.113.20",
      "lastTransport": "mqtts",
      "additionalInfo": {},
      "createdAt": "2026-10-01T08:00:00.000Z",
      "updatedAt": "2026-11-08T06:12:03.000Z"
    }
  ],
  "total": 1
}

online vaut null sur un profil dont la règle de présence est Dernière activité uniquement. GET /api/iot/devices/{deviceId} répond { "device": {...} } avec les mêmes champs, plus profileName et profileTransport.

Créer un appareil

{
    "name": "pump-station-04",
    "label": "Pump station 4",
    "deviceProfileId": "a1b2…"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices' \
  -H 'Content-Type: application/json' \
  -d '{"name":"pump-station-04","label":"Pump station 4","deviceProfileId":"a1b2…"}'

{
    "device": {
        "deviceId": "6f1c…",
        "name": "pump-station-04",
        "status": "ACTIVE",
        "…": "…"
    },
    "credential": {
        "credential": {
            "credentialId": "…",
            "type": "ACCESS_TOKEN",
            "…": "…"
        },
        "secret": {
            "token": "Xq3…"
        }
    }
}

{
    "message": "The device limit of this account is reached.",
    "code": "FORBIDDEN",
    "details": {
        "key": "max_devices",
        "limit": 43,
        "current": 43,
        "adding": 1
    }
}

{
    "message": "A device with this name already exists.",
    "code": "CONFLICT",
    "details": {
        "reason": "name_taken"
    }
}

Modifier un appareil

PATCH /api/iot/devices/{deviceId} accepte l’un quelconque de name, label, type, deviceProfileId, isGateway, additionalInfo, status (ACTIVE ou DISABLED). N’envoyez que ce qui change. Un appareil en quarantaine s’approuve via le provisioning, pas ici : « Un appareil en quarantaine s’active via le provisioning, et non en le modifiant ici. » Un nouveau nom, un nouveau profil ou une désactivation met fin à la session active de l’appareil ; il se reconnecte avec les nouveaux paramètres.

Supprimer un appareil

DELETE répond { "message": "Device deleted." }. Les relevés de l’appareil sont supprimés en arrière-plan. Un appareil encore utilisé est refusé avec 409, par exemple « The device is still in use by 1 asset placement or relation (iot_asset). » Retirez-le de son actif et supprimez d’abord ses relations : voir Placing devices et Relations.

Détails de connexion

GET /api/iot/devices/{deviceId}/connection ne renvoie aucun secret :

{
  "connection": {
    "mqtt": { "host": "mqtt.example.com", "port": 8883, "tls": true },
    "httpBase": "https://acme.example.com",
    "topics": { "telemetry": "v1/telemetry", "attributes": "v1/attributes", "rpcRequest": "v1/rpc/req/+", "rpcResponse": "v1/rpc/res/{id}" },
    "telemetryKeys": [{ "key": "temperature", "type": "number" }]
  }
}

mqtt vaut null lorsque le profil refuse MQTT sur cet écouteur ; rpcRequest et rpcResponse valent null avec le schéma Legacy compatible.

Journaux

• GET .../connections?page=1&pageSize=50 : connexions et déconnexions, les plus récentes d’abord (pages à partir de 1, pageSize jusqu’à 100).
• GET .../log?page=1&pageSize=50&source=connection|audit : le journal de connexion et les lignes d’audit de l’appareil, fusionnés, les plus récents d’abord. page × pageSize ne doit pas dépasser 1 000.

Identifiants de l’appareil

Toutes requièrent iot_device.credentials.manage. Le passage, la rotation et la révocation mettent fin immédiatement à l’ancien identifiant (sans période de tolérance) et déconnectent l’appareil.

Corps des PUT :

{ "type": "ACCESS_TOKEN" }
{ "type": "MQTT_BASIC", "username": "pump04", "clientId": "pump04", "password": null }
{ "type": "X509_CERTIFICATE", "certificateId": "…" }

Pour MQTT_BASIC, omettez password (ou mettez null) pour obtenir un mot de passe généré. Un mot de passe choisi doit comporter au moins 16 caractères, variés, et ne pas contenir le nom d’utilisateur ni l’identifiant client. Le nom d’utilisateur provision est réservé. La réponse est { "credential": {...}, "secret": { "token": "…" } } ou { ..., "secret": { "password": "…" } }, affichée une seule fois ; un identifiant X.509 n’a pas de secret. Un identifiant X.509 se renouvelle en associant un nouveau certificat : « Un identifiant X.509 se renouvelle en associant un nouveau certificat. » Voir Device credentials.

Profils d’appareils

Champs de tri : name, transport, online, updated. Une liste répond { "profiles": [...], "total": n } ; un profil, { "profile": {...} }.

Créer un profil

Un nouveau profil requiert un name (jusqu’à 128 caractères) et une onlineRule : LIVE_SOCKET (Connexion en direct), UPLINK_WINDOW (Message récent, nécessite aussi expectedIntervalS, de 60 à 604 800), ou LAST_SEEN_ONLY (Dernière activité uniquement). Chaque autre champ prend sa valeur par défaut.

{
  "name": "Cold room sensor",
  "onlineRule": "UPLINK_WINDOW",
  "expectedIntervalS": 300,
  "transportType": "MQTT",
  "telemetrySchema": [
    { "key": "temperature", "type": "number", "unit": "°C", "label": "Temperature", "min": -30, "max": 10, "decimals": 1 }
  ]
}

Champs retenus et leurs plages :

Lisez d’abord un profil existant pour voir chaque champ avec sa valeur actuelle ; l’éditeur de profils couvre les mêmes champs avec des explications, voir Profils d’appareils.

Refus

Un corps qui enfreint une règle de champ renvoie une 400 avec les problèmes dans issues, chacun avec son path et son message, par exemple online_rule_required (un nouveau profil nécessite une règle de connexion), expected_interval_required (Message récent nécessite expectedIntervalS) ou online_rule_not_allowed (la règle de connexion ne convient pas au transport).

Les autres refus portent details.reason, par exemple :