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

Développeurs

API d’appareils MQTT et HTTPS, API REST avec clés limitées, webhooks signés, limites de débit et serveurs MCP pour assistants IA.

Développeurs

Développer sur Hermetry

Connectez vos appareils via MQTT ou HTTPS, travaillez avec votre organisation grâce à l’API REST, réagissez aux événements avec des webhooks signés et laissez les assistants IA lire vos données via MCP.

Quatre voies d’accès

Une plateforme, quatre interfaces

Les appareils utilisent l’API des appareils. Vos systèmes utilisent l’API REST et les webhooks. Les assistants IA utilisent MCP. Ne placez jamais une clé d’API sur un appareil, ni un jeton d’appareil dans une intégration.

API des appareils

Les appareils envoient des données et reçoivent des commandes via MQTT ou HTTPS. Ils s’authentifient avec un jeton d’appareil, un nom d’utilisateur et un mot de passe MQTT, ou un certificat.

API REST

Votre ERP, MES, système de tickets ou script appelle Hermetry avec une clé d’API ne disposant que des droits que vous choisissez.

Webhooks

Hermetry appelle votre système lorsqu’un événement se produit : un appareil passant hors ligne, une alarme ouverte, une commande terminée.

Serveurs MCP

Un assistant IA compatible MCP appelle les outils de Hermetry avec une clé d’API ou une connexion, sans jamais pouvoir faire plus que la personne concernée.

API des appareils

Envoyez votre première mesure

Via MQTT, l’appareil maintient une seule connexion ouverte. Via HTTPS, il envoie une requête par message. Les charges utiles sont identiques.

MQTT

  • MQTT 3.1.1, TLS sur le port 8883 (TLS 1.2 ou ultérieur), vers l’hôte indiqué sur la carte Détails de connexion de l’appareil
  • Nom d’utilisateur : le jeton d’accès de l’appareil, mot de passe vide
  • Les topics commencent par v1/ ; utilisez QoS 1
  • Une mesure est un objet JSON plat, ou ts et values lorsque l’appareil connaît l’heure
CONNECT   port 8883 (TLS)
          username: <device access token>, password: empty
SUBSCRIBE v1/attributes/set   (QoS 1)
SUBSCRIBE v1/attributes/res/+ (QoS 1)
SUBSCRIBE v1/rpc/req/+        (QoS 1)
PUBLISH   v1/attributes/req/1 {}
PUBLISH   v1/telemetry        {"temperature": 21.5, "humidity": 40}
{"temperature": 21.5, "humidity": 40, "door_open": false}

{"ts": 1759572000000, "values": {"temperature": 21.5, "humidity": 40}}

HTTPS

  • Un POST par message, avec le jeton dans un en-tête Authorization: Bearer
  • Les mêmes formes de charge utile et règles de clés que pour MQTT, jusqu’à 64 KiB
  • Les commandes attendent dans une requête longue (long poll) d’au plus 60 secondes
  • Les appareils sur batterie qui se réveillent, envoient et se rendorment conviennent le mieux
curl -X POST 'https://<your-host>/api/v1/telemetry' \
  -H 'Authorization: Bearer <device access token>' \
  -H 'Content-Type: application/json' \
  -d '{"ts":1759572000000,"values":{"temperature":21.5,"humidity":40}}'
curl -X GET 'https://<your-host>/api/v1/rpc?timeout=20000' \
  -H 'Authorization: Bearer <device access token>'

API REST

Appelez l’API avec une clé limitée

Une clé d’API agit au nom du membre qui l’a créée, limitée aux droits que vous cochez pour elle. Il n’y a pas d’échange de jeton : la clé est envoyée à chaque appel.

  • Les clés ont la forme sk_live_… et ne sont affichées qu’une seule fois
  • Les droits sont choisis module par module, sans jamais dépasser les vôtres
  • Chaque clé expire : 90 jours par défaut, un an au maximum
  • Une liste d’adresses IP autorisées allant jusqu’à 100 sous-réseaux limite les endroits où une clé fonctionne
  • Les chemins se trouvent sous votre organisation : /tenant/<tenantId>/api/…
curl "https://<your host>/tenant/<tenantId>/api/iot/devices" \
  -H "Authorization: Bearer sk_live_…"
GET /tenant/{tenantId}/api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity

Webhooks

Réagissez aux événements, et vérifiez qu’ils viennent de nous

Chaque livraison est un POST avec l’événement dans le corps et une signature dans les en-têtes. Vérifiez X-Webhook-Signature-V2 avec votre secret de signature avant de faire confiance au corps.

  • Adresses HTTPS uniquement, avec jusqu’à 20 en-têtes personnalisés de votre choix
  • Les filtres d’événements ne livrent que les événements dont la charge utile correspond
  • Le même identifiant X-Webhook-Delivery à chaque nouvelle tentative, pour pouvoir écarter les doublons
  • CloudEvents 1.0 au lieu de l’enveloppe par défaut, si vous le préférez
{
  "webhookId": "…",
  "tenantId": "…",
  "event": "device.disconnected",
  "createdAt": "2026-11-03T12:00:30.000Z",
  "data": { "deviceId": "…", "name": "router-17", "reason": "timeout" }
}
import crypto from 'crypto';

function verifyWebhook(body: string, timestamp: string, signatureV2: string, secret: string): boolean {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
  // Reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureV2);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Limites

Limites à prévoir

Une limite répond 429 avec un en-tête Retry-After. Attendez ce délai, espacez les nouvelles tentatives en cas de répétition, et ne retentez jamais à l’identique une réponse 400, 401, 403, 404 ou 422.

LimitePar défautS’applique à
Limite par adresse120 requêtes par minuteChaque adresse IP appelante
Limite par clé1 000 appels par minuteChaque clé d’API
Commandes10 par minute par appareil, 600 par minute par organisationCommandes vers les appareils
Outils MCP120 appels de lecture et 20 d’écriture par minuteChaque identifiant
Corps HTTP des appareilsJusqu’à 64 KiBChaque message d’appareil

Assistants IA

Connecter un assistant IA via MCP

Chaque module dispose de son propre serveur MCP sous l’adresse de votre espace de travail. MCP reste désactivé tant qu’un administrateur ne l’active pas, et un assistant ne voit que les outils que sa personne est autorisée à utiliser.

  • Appareils, mesures et tableaux de bord : lecture seule
  • Alarmes : acquitter une alarme immédiatement ; la levée d’une alarme attend une seconde personne
  • Les réponses sont limitées à 10 secondes et 256 KiB
  • Les identifiants, jetons et clés des appareils ne sont jamais renvoyés
https://<your host>/tenant/<tenantId>/api/mcp/iot_device
https://<your host>/tenant/<tenantId>/api/mcp/telemetry
https://<your host>/tenant/<tenantId>/api/mcp/iot_alarm
https://<your host>/tenant/<tenantId>/api/mcp/dashboard

Monter en charge et étendre

Quand un appareil devient mille

Importer depuis un CSV

Ajoutez des centaines d’appareils à partir d’un fichier. Chaque import est vérifié d’abord, appliqué après relecture et peut être annulé.

Revendication et provisionnement

Appareils revendiqués avec un code, ou enregistrés à la première connexion via une session de provisionnement.

Micrologiciels signés par vagues

Vous signez les images dans votre propre chaîne et n’enregistrez que les clés publiques. Les déploiements partent par vagues.

Vos propres codecs

Décodez un capteur LoRaWAN que la bibliothèque ne couvre pas, avec un codec que vous publiez : une table JSON, jamais un script.

Bloc script

Quand les blocs prêts à l’emploi d’un flux ne suffisent pas, exécutez votre propre JavaScript sur chaque message.

Vos propres widgets

Enregistrez une carte configurée comme widget, ou créez des widgets à partir d’un modèle HTML avec leur propre formulaire de réglages.

Commencez à développer sur Hermetry

Créez une organisation, ajoutez un appareil et effectuez votre premier appel API.