Entwickler
Auf Hermetry aufbauen
Verbinden Sie Geräte über MQTT oder HTTPS, arbeiten Sie mit Ihrer Organisation über die REST API, reagieren Sie auf Ereignisse mit signierten Webhooks und lassen Sie KI-Assistenten Ihre Daten über MCP lesen.
Vier Zugänge
Eine Plattform, vier Schnittstellen
Geräte nutzen die Geräte-API. Ihre Systeme nutzen die REST API und Webhooks. KI-Assistenten nutzen MCP. Legen Sie niemals einen API-Schlüssel auf einem Gerät ab oder ein Gerätetoken in einer Integration.
Geräte-API
Geräte senden Daten und empfangen Befehle über MQTT oder HTTPS. Sie melden sich mit einem Gerätetoken, einem MQTT-Benutzernamen und -Passwort oder einem Zertifikat an.
REST API
Ihr ERP, MES, Ticketsystem oder Skript ruft Hermetry mit einem API-Schlüssel auf, der nur die von Ihnen gewählten Berechtigungen enthält.
Webhooks
Hermetry ruft Ihr System auf, wenn etwas passiert: ein Gerät geht offline, ein Alarm wird ausgelöst, ein Befehl endet.
MCP-Server
Ein KI-Assistent, der MCP unterstützt, ruft Tools von Hermetry mit einem API-Schlüssel oder einer Anmeldung auf und darf nie mehr, als diese Person darf.
Geräte-API
Senden Sie Ihren ersten Messwert
Über MQTT hält das Gerät eine Verbindung dauerhaft offen. Über HTTPS sendet es für jede Nachricht eine Anfrage. Die Nutzdaten sind dieselben.
MQTT
- MQTT 3.1.1, TLS auf Port 8883 (TLS 1.2 oder höher), zum Host auf der Karte „Verbindungsdetails“ des Geräts
- Benutzername: das Zugriffstoken des Geräts, Passwort leer
- Themen beginnen mit
v1/; QoS 1 verwenden - Ein Messwert ist ein flaches JSON-Objekt oder
tsundvalues, wenn das Gerät die Zeit kennt
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
- Ein POST pro Nachricht, mit dem Token in einem
Authorization: Bearer-Header - Dieselben Nutzdatenformen und Schlüsselregeln wie bei MQTT, bis zu 64 KiB
- Befehle warten in einem Long Poll von bis zu 60 Sekunden
- Batteriebetriebene Geräte, die aufwachen, senden und wieder schlafen, passen am besten
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>'
REST API
Rufen Sie die API mit einem eingeschränkten Schlüssel auf
Ein API-Schlüssel handelt als das Mitglied, das ihn erstellt hat, begrenzt auf die Berechtigungen, die Sie ihm zuweisen. Es gibt keinen Token-Austausch: Der Schlüssel wird bei jedem Aufruf gesendet.
- Schlüssel sehen so aus:
sk_live_…und werden nur einmal angezeigt - Berechtigungen werden je Modul einzeln vergeben, nie mehr als Ihre eigenen
- Jeder Schlüssel läuft ab: standardmäßig nach 90 Tagen, höchstens nach einem Jahr
- Eine IP-Allowlist mit bis zu 100 Subnetzen begrenzt, wo ein Schlüssel funktioniert
- Pfade liegen unter Ihrer 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
Auf Ereignisse reagieren und prüfen, dass sie von uns stammen
Jede Zustellung ist ein POST mit dem Ereignis im Body und einer Signatur in den Headern. Prüfen Sie X-Webhook-Signature-V2 mit Ihrem Signaturgeheimnis, bevor Sie dem Body vertrauen.
- Nur HTTPS-Adressen, mit bis zu 20 eigenen benutzerdefinierten Headern
- Ereignisfilter liefern nur die Ereignisse, deren Nutzdaten passen
- Dieselbe
X-Webhook-Delivery-ID bei jedem Wiederholungsversuch, damit Sie Duplikate verwerfen können - CloudEvents 1.0 statt des Standardformats, falls gewünscht
{
"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);
}
Limits
Einzuplanende Limits
Ein Limit antwortet mit 429 und einem Retry-After-Header. Warten Sie so lange, verlängern Sie bei Wiederholungen die Abstände und wiederholen Sie einen 400, 401, 403, 404 oder 422 nie unverändert.
| Limit | Standard | Gilt für |
|---|---|---|
| Adresslimit | 120 Anfragen pro Minute | Jede aufrufende IP-Adresse |
| Schlüssellimit | 1.000 Aufrufe pro Minute | Jeder API-Schlüssel |
| Befehle | 10 pro Minute je Gerät, 600 pro Minute je Organisation | Befehle an Geräte |
| MCP-Tools | 120 Lese- und 20 Schreibaufrufe pro Minute | Jeder Berechtigungsnachweis |
| Geräte-HTTP-Body | Bis zu 64 KiB | Jede Geräte-Nachricht |
KI-Assistenten
Einen KI-Assistenten über MCP verbinden
Jedes Modul hat seinen eigenen MCP-Server unter der Adresse Ihres Arbeitsbereichs. MCP ist aus, bis ein Administrator es einschaltet, und ein Assistent sieht nur die Tools, die seine Person nutzen darf.
- Geräte, Messwerte und Dashboards: nur lesen
- Alarme: einen sofort bestätigen; das Aufheben wartet auf eine zweite Person
- Antworten sind auf 10 Sekunden und 256 KiB begrenzt
- Gerätezugangsdaten, Tokens und Schlüssel werden nie zurückgegeben
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
Skalieren und erweitern
Wenn aus einem Gerät tausend werden
Import aus CSV
Fügen Sie Hunderte Geräte aus einer Datei hinzu. Jeder Import wird zuerst geprüft, nach Freigabe angewendet und kann rückgängig gemacht werden.
Beanspruchung und Provisionierung
Geräte, die mit einem Code beansprucht werden, oder beim ersten Verbinden über eine Provisionierungssitzung registriert werden.
Signierte Firmware in Wellen
Sie signieren Images in Ihrer eigenen Pipeline und registrieren nur öffentliche Schlüssel. Rollouts erfolgen in Wellen.
Eigene Codecs
Dekodieren Sie einen LoRaWAN-Sensor, den die Bibliothek nicht abdeckt, mit einem Codec, den Sie veröffentlichen: eine JSON-Tabelle, kein Skript.
Skriptblock
Wenn die fertigen Blöcke eines Flows nicht reichen, führen Sie Ihr eigenes JavaScript für jede Nachricht aus.
Eigene Widgets
Speichern Sie eine konfigurierte Karte als Widget oder erstellen Sie Widgets aus einer HTML-Vorlage mit eigenem Einstellungsformular.
Referenz
API-Referenz
Starten Sie mit Hermetry
Legen Sie eine Organisation an, fügen Sie ein Gerät hinzu und tätigen Sie Ihren ersten API-Aufruf.

