This page is for integrators who open a router’s web panel from their own tools, for example a support console that sends a technician straight into the panel of a customer’s router. How panel sessions work for people is on Remote access to a router’s panel; the limits and the reasons a session ends are on Remote access limits and audit.
Paths are under https://<your host>/tenant/<tenantId>. Conventions are in REST API basics.
Routes
| Method | Path | Permission | Does |
|---|---|---|---|
| GET | /api/iot/devices/{deviceId}/remote-access | iot_remote_access.panel.open | Whether a session can be opened on this router, and its open sessions |
| POST | /api/iot/remote-access/sessions | iot_remote_access.panel.open | Open a panel session |
| POST | /api/iot/remote-access/sessions/{sessionId} | iot_remote_access.panel.open | A new entry link for the session’s opener |
| DELETE | /api/iot/remote-access/sessions/{sessionId} | iot_remote_access.panel.open | Close a session |
| GET | /api/iot/remote-access/sessions | iot_remote_access.sessions.read | The organisation’s sessions and this month’s use |
Both permissions are Admin permissions by default. The command that tells a router to open its tunnel cannot be sent through the Commands API (it answers 403 rpc_method_reserved); these routes are the only way, so every session is checked, limited and audited.
Who the session belongs to
A session opened with a key is opened as the key’s holder: the sessions list shows the holder under Opened by, and the audit log records them. Only requests made as the opener can get an entry link for the session, so the holder can also re-enter it from the app. Any member or key with iot_remote_access.panel.open can close any session of the organisation.
The session ends when the holder leaves the organisation or their access changes, like a session opened in the app. Revoking the key does not close sessions it already opened: close them with DELETE when your program is done.
Warning
The entry link (openUrl) is a credential. Whoever opens it first, within 60 seconds, enters the router’s panel without signing in to Hermetry. Hand it only to the person who needs it, over a channel you trust, and never write it to a log.
Check a router first
GET /api/iot/devices/{deviceId}/remote-access
{ "configured": true, "available": false, "reason": "offline", "metered": false, "open": [] }
reason is null when a session can be opened, otherwise one of not_configured, device_not_found, not_claimed, unsupported, device_not_active, certificate_inactive or offline (the same reasons the open route refuses with). metered is true when the router is on its mobile uplink. open lists the router’s open sessions.
Open a session
POST /api/iot/remote-access/sessions
| Field | Rule |
|---|---|
deviceId | Required. The router’s device id |
target | panel (the default and the only value) |
confirm | true to accept the data cap on a mobile uplink |
The body is strict: an unknown field is a 400.
On a mobile (LTE) uplink the first call creates nothing and answers 200 { "requiresConfirm": "metered", "capBytes": 52428800 }: how many bytes the session may move before it is closed. Send the same body again with "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}'
The call waits up to 15 seconds for the router to accept. Then it answers 201:
{
"sessionId": "dk3v…",
"openUrl": "https://dk3v….<panel domain>/__open?t=…",
"expiresAt": "2026-11-17T14:00:00.000Z",
"metered": false
}
expiresAt is the hard end, 4 hours after opening. The router must connect its tunnel within 90 seconds, or the session ends (no_dial).
New entry link
POST /api/iot/remote-access/sessions/{sessionId} (no body) answers 200 { "openUrl": "…" } with a fresh one-time link, for example when the first one expired unused. Only the opener gets one.
Close a session
DELETE /api/iot/remote-access/sessions/{sessionId} ends the session at once: the browser tab stops working within about a second and the router is told to close the tunnel. The answer is 200 { "session": {...} }. Closing a session that has already ended answers the same, without recording anything twice.
List sessions
GET /api/iot/remote-access/sessions?state=all&deviceId=…&limit=100
| Parameter | Values | Default |
|---|---|---|
state | open or all | open |
deviceId | A device id | all routers |
limit | 1 or more; at most 500 rows are returned | 100 |
Unknown parameters are refused with 400. Sessions come newest first:
{
"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 is PENDING (waiting for the router), CONNECTED or CLOSED. closeReason is one of the codes in Remote access limits and audit. mine is true for sessions opened by the key’s holder. In usage, a null limit means your plan sets none. Ended sessions are kept for 180 days.
Refusals
Every refusal carries details.reason.
| Status | details.reason | code | Message |
|---|---|---|---|
| 404 | device_not_found | NOT_FOUND | Device not found. |
| 409 | not_claimed | CONFLICT | Refused: the device is not a claimed licensed router |
| 409 | unsupported | CONFLICT | This router does not support panel access yet. Update its firmware. |
| 409 | device_not_active | CONFLICT | The device is not active. |
| 409 | certificate_inactive | CONFLICT | The router has no valid certificate. Provision it again. |
| 409 | offline | CONFLICT | The router is offline. |
| 403 | monthly_bytes | QUOTA_EXCEEDED | This month’s panel data allowance is used up. (details.limit) |
| 409 | device_busy | CONFLICT | This router already has 3 open panel sessions. Close one first. |
| 403 | tenant_limit | QUOTA_EXCEEDED | Your plan’s limit of open panel sessions is reached. Close one first. (details.limit, details.current) |
| 409 | opt_in | CONFLICT | Panel access is switched off on this router. Switch on “Allow panel access from my cloud account” on the router’s Cloud page. |
| 409 | router_busy | CONFLICT | The router refused: it already has the most panel sessions it allows. |
| 409 | router_refused | CONFLICT | The router refused the panel session. (details.error) |
| 504 | router_unreachable | PROVIDER_UNAVAILABLE | The router did not answer. Try again in a moment. |
| 503 | not_configured | PROVIDER_UNAVAILABLE | Panel access is not set up on this installation. |
| 404 | session_not_found | NOT_FOUND | Panel session not found. |
| 409 | session_closed | CONFLICT | This panel session has ended. |
| 403 | not_opener | FORBIDDEN | Only the person who opened this panel session can enter it. |
Retry only router_unreachable and offline, after a pause. For opt_in, someone at the router must switch panel access on; it cannot be done from Hermetry.
Limits
| Limit | Value |
|---|---|
| Open sessions per router | 3 |
| Open sessions per organisation | Your plan’s value (usage.openLimit) |
| Panel data per month | Your plan’s value (usage.monthBytesLimit) |
| Session length | 4 hours from opening, whatever the activity |
| Idle timeout | 30 minutes without traffic |
| Entry link | One use, within 60 seconds |
| Router must connect | Within 90 seconds |
| Data cap on a mobile uplink | capBytes per session |

