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
| Methode | Pfad | Berechtigung | Funktion |
|---|---|---|---|
| GET | /api/iot/devices/{deviceId}/remote-access | iot_remote_access.panel.open | Ob auf diesem Router eine Sitzung geöffnet werden kann, und seine offenen Sitzungen |
| POST | /api/iot/remote-access/sessions | iot_remote_access.panel.open | Oberflächen-Sitzung öffnen |
| POST | /api/iot/remote-access/sessions/{sessionId} | iot_remote_access.panel.open | Ein neuer Einstiegslink für den Öffner der Sitzung |
| DELETE | /api/iot/remote-access/sessions/{sessionId} | iot_remote_access.panel.open | Sitzung schließen |
| GET | /api/iot/remote-access/sessions | iot_remote_access.sessions.read | Die 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
| Feld | Regel |
|---|---|
deviceId | Pflichtfeld. Die Geräte-ID des Routers |
target | panel (der Standardwert und der einzige Wert) |
confirm | true, 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
| Parameter | Werte | Standard |
|---|---|---|
state | open oder all | open |
deviceId | Eine Geräte-ID | alle Router |
limit | 1 oder mehr; höchstens 500 Zeilen werden zurückgegeben | 100 |
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.
| Status | details.reason | code | Meldung |
|---|---|---|---|
| 404 | device_not_found | NOT_FOUND | Gerät nicht gefunden. |
| 409 | not_claimed | CONFLICT | Abgelehnt: Das Gerät ist kein beanspruchter lizenzierter Router |
| 409 | unsupported | CONFLICT | Dieser Router unterstützt den Oberflächenzugriff noch nicht. Aktualisieren Sie seine Firmware. |
| 409 | device_not_active | CONFLICT | Das Gerät ist nicht aktiv. |
| 409 | certificate_inactive | CONFLICT | Der Router hat kein gültiges Zertifikat. Stellen Sie es erneut bereit. |
| 409 | offline | CONFLICT | Der Router ist offline. |
| 403 | monthly_bytes | QUOTA_EXCEEDED | Das Datenkontingent für die Oberfläche in diesem Monat ist aufgebraucht. (details.limit) |
| 409 | device_busy | CONFLICT | Dieser Router hat bereits 3 offene Oberflächen-Sitzungen. Schließen Sie zuerst eine. |
| 403 | tenant_limit | QUOTA_EXCEEDED | Das Limit offener Oberflächen-Sitzungen Ihres Tarifs ist erreicht. Schließen Sie zuerst eine. (details.limit, details.current) |
| 409 | opt_in | CONFLICT | Der Oberflächenzugriff ist auf diesem Router deaktiviert. Aktivieren Sie auf der Cloud-Seite des Routers „Oberflächenzugriff aus meinem Cloud-Konto erlauben“. |
| 409 | router_busy | CONFLICT | Der Router hat abgelehnt: Er hat bereits die höchstzulässige Anzahl an Oberflächen-Sitzungen. |
| 409 | router_refused | CONFLICT | Der Router hat die Oberflächen-Sitzung abgelehnt. (details.error) |
| 504 | router_unreachable | PROVIDER_UNAVAILABLE | Der Router hat nicht geantwortet. Versuchen Sie es in Kürze erneut. |
| 503 | not_configured | PROVIDER_UNAVAILABLE | Der Oberflächenzugriff ist auf dieser Installation nicht eingerichtet. |
| 404 | session_not_found | NOT_FOUND | Oberflächen-Sitzung nicht gefunden. |
| 409 | session_closed | CONFLICT | Diese Oberflächen-Sitzung ist beendet. |
| 403 | not_opener | FORBIDDEN | Nur 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
| Grenze | Wert |
|---|---|
| Offene Sitzungen je Router | 3 |
| Offene Sitzungen je Organisation | Der Wert Ihres Tarifs (usage.openLimit) |
| Oberflächendaten pro Monat | Der Wert Ihres Tarifs (usage.monthBytesLimit) |
| Sitzungsdauer | 4 Stunden ab dem Öffnen, unabhängig von der Aktivität |
| Leerlauf-Timeout | 30 Minuten ohne Datenverkehr |
| Einstiegslink | Einmalig, innerhalb von 60 Sekunden |
| Router muss sich verbinden | Innerhalb von 90 Sekunden |
| Datenlimit bei mobiler Verbindung | capBytes je Sitzung |

