Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Remote-Access-API

Panel-Sitzungen zu beanspruchten lizenzierten Routern aus einem Programm öffnen, erneut betreten, schließen und auflisten, mit allen Ablehnungen und Grenzen.

Diese Seite richtet sich an Integratoren, die die Web-Oberfläche eines Routers aus ihren eigenen Werkzeugen öffnen, zum Beispiel eine Support-Konsole, die einen Techniker direkt in die Oberfläche des Routers eines Kunden schickt. Wie Oberflächen-Sitzungen für Nutzer funktionieren, steht unter Remote-Zugriff auf die Oberfläche eines Routers; die Grenzen und die Gründe, aus denen eine Sitzung endet, stehen unter Remote-Zugriff: Grenzen und Protokollierung.

Die Pfade liegen unter https://<your host>/tenant/<tenantId>. Die Konventionen sind unter REST-API-Grundlagen beschrieben.

Routen

MethodePfadBerechtigungFunktion
GET/api/iot/devices/{deviceId}/remote-accessiot_remote_access.panel.openOb auf diesem Router eine Sitzung geöffnet werden kann, und seine offenen Sitzungen
POST/api/iot/remote-access/sessionsiot_remote_access.panel.openOberflächen-Sitzung öffnen
POST/api/iot/remote-access/sessions/{sessionId}iot_remote_access.panel.openEin neuer Einstiegslink für den Öffner der Sitzung
DELETE/api/iot/remote-access/sessions/{sessionId}iot_remote_access.panel.openSitzung schließen
GET/api/iot/remote-access/sessionsiot_remote_access.sessions.readDie Sitzungen der Organisation und die Nutzung in diesem Monat

Beide Berechtigungen sind standardmäßig Admin-Berechtigungen. Der Befehl, der einem Router sagt, dass er seinen Tunnel öffnet, kann nicht über die Commands API gesendet werden (er antwortet mit 403 rpc_method_reserved); diese Routen sind der einzige Weg, sodass jede Sitzung geprüft, begrenzt und protokolliert wird.

Wem die Sitzung gehört

Eine mit einem Schlüssel geöffnete Sitzung wird als Inhaber des Schlüssels geöffnet: Die Sitzungsliste zeigt den Inhaber unter Geöffnet von, und das Audit-Protokoll erfasst ihn. Einen Einstiegslink für die Sitzung können nur Anfragen erhalten, die als Öffner gestellt werden, sodass der Inhaber sie auch aus der App wieder betreten kann. Jedes Mitglied oder jeder Schlüssel mit iot_remote_access.panel.open kann jede Sitzung der Organisation schließen.

Die Sitzung endet, wenn der Inhaber die Organisation verlässt oder sich sein Zugriff ändert, wie bei einer in der App geöffneten Sitzung. Das Widerrufen des Schlüssels schließt die bereits von ihm geöffneten Sitzungen nicht: Schließen Sie sie mit DELETE, wenn Ihr Programm fertig ist.

Warnung

Der Einstiegslink (openUrl) ist ein Zugangsdatum. Wer ihn zuerst öffnet, innerhalb von 60 Sekunden, gelangt ohne Anmeldung bei Hermetry in die Oberfläche des Routers. Geben Sie ihn nur der Person weiter, die ihn benötigt, über einen vertrauenswürdigen Kanal, und schreiben Sie ihn niemals in ein Protokoll.

Router zuerst prüfen

GET /api/iot/devices/{deviceId}/remote-access

{ "configured": true, "available": false, "reason": "offline", "metered": false, "open": [] }

reason ist null, wenn eine Sitzung geöffnet werden kann, andernfalls einer der Werte not_configured, device_not_found, not_claimed, unsupported, device_not_active, certificate_inactive oder offline (dieselben Gründe, mit denen die Öffnen-Route ablehnt). metered ist true, wenn der Router über seine mobile Verbindung läuft. open listet die offenen Sitzungen des Routers auf.

Sitzung öffnen

POST /api/iot/remote-access/sessions

FeldRegel
deviceIdPflichtfeld. Die Geräte-ID des Routers
targetpanel (der Standardwert und der einzige Wert)
confirmtrue, um das Datenlimit einer mobilen Verbindung zu akzeptieren

Der Body ist streng: Ein unbekanntes Feld führt zu einer 400.

Bei einer mobilen (LTE-)Verbindung erstellt der erste Aufruf nichts und antwortet mit 200 { "requiresConfirm": "metered", "capBytes": 52428800 }: wie viele Bytes die Sitzung übertragen darf, bevor sie geschlossen wird. Senden Sie denselben Body erneut mit "confirm": true.

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/remote-access/sessions' \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"deviceId":"6f1c…","confirm":true}'

Der Aufruf wartet bis zu 15 Sekunden, bis der Router annimmt. Dann antwortet er mit 201:

{
  "sessionId": "dk3v…",
  "openUrl": "https://dk3v….<panel domain>/__open?t=…",
  "expiresAt": "2026-11-17T14:00:00.000Z",
  "metered": false
}

expiresAt ist das feste Ende, 4 Stunden nach dem Öffnen. Der Router muss seinen Tunnel innerhalb von 90 Sekunden verbinden, sonst endet die Sitzung (no_dial).

Neuer Einstiegslink

POST /api/iot/remote-access/sessions/{sessionId} (ohne Body) antwortet mit 200 { "openUrl": "…" } und einem neuen Einmal-Link, zum Beispiel wenn der erste ungenutzt abgelaufen ist. Nur der Öffner erhält einen.

Sitzung schließen

DELETE /api/iot/remote-access/sessions/{sessionId} beendet die Sitzung sofort: Der Browser-Tab funktioniert innerhalb von etwa einer Sekunde nicht mehr, und der Router wird angewiesen, den Tunnel zu schließen. Die Antwort lautet 200 { "session": {...} }. Das Schließen einer bereits beendeten Sitzung ergibt dieselbe Antwort, ohne etwas doppelt zu erfassen.

Sitzungen auflisten

GET /api/iot/remote-access/sessions?state=all&deviceId=…&limit=100

ParameterWerteStandard
stateopen oder allopen
deviceIdEine Geräte-IDalle Router
limit1 oder mehr; höchstens 500 Zeilen werden zurückgegeben100

Unbekannte Parameter werden mit 400 abgelehnt. Die Sitzungen kommen neueste zuerst:

{
  "sessions": [
    {
      "sessionId": "dk3v…", "deviceId": "6f1c…", "userId": "u-55…", "state": "CONNECTED",
      "closeReason": null, "metered": false,
      "createdAt": "2026-11-17T10:00:00.000Z", "expiresAt": "2026-11-17T14:00:00.000Z",
      "connectedAt": "2026-11-17T10:00:04.000Z", "lastActivityAt": "2026-11-17T10:12:40.000Z", "closedAt": null,
      "bytesUp": 182044, "bytesDown": 5310221, "mine": true
    }
  ],
  "usage": { "monthBytes": 734003200, "monthBytesLimit": 10737418240, "openLimit": 10, "open": 2 }
}

state ist PENDING (wartet auf den Router), CONNECTED oder CLOSED. closeReason ist einer der Codes unter Remote-Zugriff: Grenzen und Protokollierung. mine ist true für Sitzungen, die der Inhaber des Schlüssels geöffnet hat. Bei usage bedeutet ein null-Limit, dass Ihr Tarif keines festlegt. Beendete Sitzungen werden 180 Tage aufbewahrt.

Ablehnungen

Jede Ablehnung enthält details.reason.

Statusdetails.reasoncodeMeldung
404device_not_foundNOT_FOUNDGerät nicht gefunden.
409not_claimedCONFLICTAbgelehnt: Das Gerät ist kein beanspruchter lizenzierter Router
409unsupportedCONFLICTDieser Router unterstützt den Oberflächenzugriff noch nicht. Aktualisieren Sie seine Firmware.
409device_not_activeCONFLICTDas Gerät ist nicht aktiv.
409certificate_inactiveCONFLICTDer Router hat kein gültiges Zertifikat. Stellen Sie es erneut bereit.
409offlineCONFLICTDer Router ist offline.
403monthly_bytesQUOTA_EXCEEDEDDas Datenkontingent für die Oberfläche in diesem Monat ist aufgebraucht. (details.limit)
409device_busyCONFLICTDieser Router hat bereits 3 offene Oberflächen-Sitzungen. Schließen Sie zuerst eine.
403tenant_limitQUOTA_EXCEEDEDDas Limit offener Oberflächen-Sitzungen Ihres Tarifs ist erreicht. Schließen Sie zuerst eine. (details.limit, details.current)
409opt_inCONFLICTDer Oberflächenzugriff ist auf diesem Router deaktiviert. Aktivieren Sie auf der Cloud-Seite des Routers „Oberflächenzugriff aus meinem Cloud-Konto erlauben“.
409router_busyCONFLICTDer Router hat abgelehnt: Er hat bereits die höchstzulässige Anzahl an Oberflächen-Sitzungen.
409router_refusedCONFLICTDer Router hat die Oberflächen-Sitzung abgelehnt. (details.error)
504router_unreachablePROVIDER_UNAVAILABLEDer Router hat nicht geantwortet. Versuchen Sie es in Kürze erneut.
503not_configuredPROVIDER_UNAVAILABLEDer Oberflächenzugriff ist auf dieser Installation nicht eingerichtet.
404session_not_foundNOT_FOUNDOberflächen-Sitzung nicht gefunden.
409session_closedCONFLICTDiese Oberflächen-Sitzung ist beendet.
403not_openerFORBIDDENNur die Person, die diese Oberflächen-Sitzung geöffnet hat, kann sie betreten.

Wiederholen Sie nur router_unreachable und offline, nach einer kurzen Pause. Bei opt_in muss jemand am Router den Oberflächenzugriff einschalten; das kann nicht aus Hermetry heraus erfolgen.

Grenzen

GrenzeWert
Offene Sitzungen je Router3
Offene Sitzungen je OrganisationDer Wert Ihres Tarifs (usage.openLimit)
Oberflächendaten pro MonatDer Wert Ihres Tarifs (usage.monthBytesLimit)
Sitzungsdauer4 Stunden ab dem Öffnen, unabhängig von der Aktivität
Leerlauf-Timeout30 Minuten ohne Datenverkehr
EinstiegslinkEinmalig, innerhalb von 60 Sekunden
Router muss sich verbindenInnerhalb von 90 Sekunden
Datenlimit bei mobiler VerbindungcapBytes je Sitzung