DRAFT — Preliminary version, do not share. · Version préliminaire, ne pas partager.

Appareils en stock et clés de provisionnement

Les appareils en stock vous permettent d'enregistrer des appareils à l'usine, avant de savoir à quel client ou registre ils appartiendront, puis de les affecter à un registre lors de l'installation. Cette page vous guide à travers le flux complet : clé de provisionnement, enregistrement en usine, provisionnement dans un registre et première connexion de l'appareil.

Cycle de vie d'un appareil en stock : enregistrement à l'usine, provisionnement dans un registre, première connexion

Fonctionnement

Un appareil en stock est créé avec son numéro de série et ses informations d'identification (clé publique et algorithme). Il reste non provisionné et ne peut pas se connecter tant que quelqu'un ne l'a pas affecté à un registre. L'appareil ne connaît lui-même que son numéro de série, son projet, sa région et son type d'actif. Au démarrage, il demande à la plateforme à quel registre il appartient, puis se connecte dès qu'il obtient une réponse.

            store                    provision(registry_id)
  (none) ─────────▶ unprovisioned ─────────────────────────▶ provisioned
                      ▲      │                                    │
                      │      └─ delete ─▶ (none)                  │
                      └──────────────── deprovision ◀─────────────┘

Chaque étape utilise des informations d'identification différentes :

Provisionnement d'un appareil en stock : les appels API à chaque étape

Étape Qui appelle Informations d'identification (Authorization: Bearer)
Créer une clé de provisionnement Un administrateur du projet Jeton utilisateur OAuth avec l'autorisation de mettre à jour le projet
Enregistrer l'appareil en stock Outillage d'usine Clé de provisionnement
Provisionner dans un registre Outil d'installation ou intégration Clé de provisionnement
Rechercher le registre L'appareil JWT de l'appareil signé avec sa clé privée
Déprovisionner Un opérateur ou une intégration Jeton OAuth avec l'autorisation de supprimer des appareils

Tous les chemins ci-dessous sont relatifs à https://devices.fundamentum-iot.com/api/v3/projects/<project-id>/regions/1.

Avant de commencer

1. Créer une clé de provisionnement

Une clé de provisionnement autorise les opérations sur les appareils en stock pour un projet. Elle est active à partir de start_at (inclus) jusqu'à end_at (exclu). Les dates utilisent le format YYYY-MM-DD et sont interprétées à minuit UTC.

curl -s -X POST https://devices.fundamentum-iot.com/api/v3/projects/<project-id>/regions/1/provisioning-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"start_at": "2026-10-16", "end_at": "2027-10-16"}'

La réponse contient la key (un UUID). Conservez-la dans le magasin de secrets de votre outillage d'usine.

Opération Appel
Lister les clés actives GET /provisioning-keys
Obtenir une clé GET /provisioning-keys/<key>
Supprimer une clé DELETE /provisioning-keys/<key>

2. Enregistrer l'appareil à l'usine

Pour chaque appareil, envoyez son numéro de série et sa clé publique :

curl -s -X POST https://devices.fundamentum-iot.com/api/v3/projects/<project-id>/regions/1/asset-types/<asset-type-id>/shelf-devices \
  -H "Authorization: Bearer <provisioning-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "<serial-number>",
    "algorithm": "RS256",
    "secret": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  }'

Le numéro de série doit déjà être en minuscules et ne contenir que des lettres, des chiffres, _ et -. Un appareil en stock est identifié par son projet, son type d'actif et son numéro de série. La réponse renvoie l'appareil en stock (id, project_id, serial_number, secret, algorithm et horodatages).

3. Provisionner l'appareil dans un registre

Lors de l'installation, une fois la destination connue, affectez l'appareil à un registre :

curl -s -X POST https://devices.fundamentum-iot.com/api/v3/projects/<project-id>/regions/1/asset-types/<asset-type-id>/shelf-devices/<serial-number>/provision \
  -H "Authorization: Bearer <provisioning-key>" \
  -H "Content-Type: application/json" \
  -d '{"registry_id": <registry-id>}'

La réponse renvoie le device_id, la configuration de l'appareil et les détails de connexion mqtt (host, port, client_id). Rien n'est transmis à l'appareil : il apprend son registre à l'étape suivante. Provisionner un appareil en stock déjà provisionné renvoie 422 ; déprovisionnez-le d'abord.

4. Laisser l'appareil rechercher son registre

L'appareil signe un JWT avec sa clé privée (consultez Connect over MQTTS) et demande son registre :

curl -s https://devices.fundamentum-iot.com/api/v3/projects/<project-id>/regions/1/asset-types/<asset-type-id>/shelf-devices/<serial-number>/registry-id \
  -H "Authorization: Bearer <device-jwt>"
Statut Signification Action de l'appareil
200 Renvoie registry_id, mqtt_host et mqtt_port. Se connecte en MQTTS avec la même clé.
401 L'appareil n'est pas encore provisionné. Attend, puis réessaie.

La bibliothèque MCU implémente cette recherche dans edge_provisioning_get_registration.

Gérer les appareils en stock

Tâche Appel Informations d'identification
Obtenir un appareil en stock GET /asset-types/<asset-type-id>/shelf-devices/<serial-number> Clé de provisionnement
Déprovisionner, afin de pouvoir le déplacer vers un autre registre DELETE /asset-types/<asset-type-id>/shelf-devices/<serial-number>/provision Jeton OAuth avec l'autorisation de supprimer des appareils
Supprimer l'enregistrement en stock DELETE /asset-types/<asset-type-id>/shelf-devices/<serial-number> Clé de provisionnement

Le déprovisionnement supprime l'appareil de son registre et remet l'appareil en stock à l'état non provisionné. La suppression de l'enregistrement en stock ne supprime que cet enregistrement ; déprovisionnez donc d'abord un appareil provisionné.

Étapes suivantes