New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Remote access API

Open, re-enter, close and list panel sessions to claimed licensed routers from a program, with every refusal and limit.

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

MethodPathPermissionDoes
GET/api/iot/devices/{deviceId}/remote-accessiot_remote_access.panel.openWhether a session can be opened on this router, and its open sessions
POST/api/iot/remote-access/sessionsiot_remote_access.panel.openOpen a panel session
POST/api/iot/remote-access/sessions/{sessionId}iot_remote_access.panel.openA new entry link for the session’s opener
DELETE/api/iot/remote-access/sessions/{sessionId}iot_remote_access.panel.openClose a session
GET/api/iot/remote-access/sessionsiot_remote_access.sessions.readThe 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

FieldRule
deviceIdRequired. The router’s device id
targetpanel (the default and the only value)
confirmtrue 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

ParameterValuesDefault
stateopen or allopen
deviceIdA device idall routers
limit1 or more; at most 500 rows are returned100

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.

Statusdetails.reasoncodeMessage
404device_not_foundNOT_FOUNDDevice not found.
409not_claimedCONFLICTRefused: the device is not a claimed licensed router
409unsupportedCONFLICTThis router does not support panel access yet. Update its firmware.
409device_not_activeCONFLICTThe device is not active.
409certificate_inactiveCONFLICTThe router has no valid certificate. Provision it again.
409offlineCONFLICTThe router is offline.
403monthly_bytesQUOTA_EXCEEDEDThis month’s panel data allowance is used up. (details.limit)
409device_busyCONFLICTThis router already has 3 open panel sessions. Close one first.
403tenant_limitQUOTA_EXCEEDEDYour plan’s limit of open panel sessions is reached. Close one first. (details.limit, details.current)
409opt_inCONFLICTPanel access is switched off on this router. Switch on “Allow panel access from my cloud account” on the router’s Cloud page.
409router_busyCONFLICTThe router refused: it already has the most panel sessions it allows.
409router_refusedCONFLICTThe router refused the panel session. (details.error)
504router_unreachablePROVIDER_UNAVAILABLEThe router did not answer. Try again in a moment.
503not_configuredPROVIDER_UNAVAILABLEPanel access is not set up on this installation.
404session_not_foundNOT_FOUNDPanel session not found.
409session_closedCONFLICTThis panel session has ended.
403not_openerFORBIDDENOnly 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

LimitValue
Open sessions per router3
Open sessions per organisationYour plan’s value (usage.openLimit)
Panel data per monthYour plan’s value (usage.monthBytesLimit)
Session length4 hours from opening, whatever the activity
Idle timeout30 minutes without traffic
Entry linkOne use, within 60 seconds
Router must connectWithin 90 seconds
Data cap on a mobile uplinkcapBytes per session