Esta página es para integradores que abren el panel web de un router desde sus propias herramientas, por ejemplo una consola de soporte que lleva a un técnico directamente al panel del router de un cliente. Cómo funcionan las sesiones del panel para las personas está en Acceso remoto al panel de un router; los límites y los motivos por los que una sesión termina están en Límites y auditoría del acceso remoto.
Las rutas están bajo https://<your host>/tenant/<tenantId>. Las convenciones están en Fundamentos de la API REST.
Rutas
| Método | Ruta | Permiso | Función |
|---|---|---|---|
| GET | /api/iot/devices/{deviceId}/remote-access | iot_remote_access.panel.open | Si se puede abrir una sesión en este router, y sus sesiones abiertas |
| POST | /api/iot/remote-access/sessions | iot_remote_access.panel.open | Abrir una sesión del panel |
| POST | /api/iot/remote-access/sessions/{sessionId} | iot_remote_access.panel.open | Un nuevo enlace de entrada para quien abrió la sesión |
| DELETE | /api/iot/remote-access/sessions/{sessionId} | iot_remote_access.panel.open | Cerrar una sesión |
| GET | /api/iot/remote-access/sessions | iot_remote_access.sessions.read | Las sesiones de la organización y el uso de este mes |
Ambos permisos son permisos de administrador por defecto. El comando que indica a un router que abra su túnel no se puede enviar a través de la API de comandos (responde 403 rpc_method_reserved); estas rutas son la única vía, de modo que cada sesión se comprueba, se limita y se audita.
A quién pertenece la sesión
Una sesión abierta con una clave se abre como el titular de la clave: la lista de sesiones muestra al titular bajo Abierta por, y el registro de auditoría lo registra. Solo las solicitudes hechas como quien abrió la sesión pueden obtener un enlace de entrada para ella, de modo que el titular también puede volver a entrar desde la aplicación. Cualquier miembro o clave con iot_remote_access.panel.open puede cerrar cualquier sesión de la organización.
La sesión termina cuando el titular abandona la organización o cambian sus accesos, igual que una sesión abierta desde la aplicación. Revocar la clave no cierra las sesiones que ya abrió: ciérrelas con DELETE cuando su programa termine.
Advertencia
El enlace de entrada (openUrl) es una credencial. Quien lo abra primero, dentro de 60 segundos, entra en el panel del router sin iniciar sesión en Hermetry. Entréguelo solo a la persona que lo necesita, por un canal de confianza, y nunca lo escriba en un registro.
Compruebe primero un router
GET /api/iot/devices/{deviceId}/remote-access
{ "configured": true, "available": false, "reason": "offline", "metered": false, "open": [] }
reason es null cuando se puede abrir una sesión; en caso contrario, es uno de not_configured, device_not_found, not_claimed, unsupported, device_not_active, certificate_inactive u offline (los mismos motivos con los que la ruta de apertura rechaza). metered es true cuando el router está en su enlace móvil. open enumera las sesiones abiertas del router.
Abrir una sesión
POST /api/iot/remote-access/sessions
| Campo | Regla |
|---|---|
deviceId | Obligatorio. El id de dispositivo del router |
target | panel (el valor por defecto y el único) |
confirm | true para aceptar el límite de datos en un enlace móvil |
El cuerpo es estricto: un campo desconocido produce un 400.
En un enlace móvil (LTE), la primera llamada no crea nada y responde 200 { "requiresConfirm": "metered", "capBytes": 52428800 }: cuántos bytes puede mover la sesión antes de cerrarse. Envíe de nuevo el mismo cuerpo con "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}'
La llamada espera hasta 15 segundos a que el router acepte. Después responde 201:
{
"sessionId": "dk3v…",
"openUrl": "https://dk3v….<panel domain>/__open?t=…",
"expiresAt": "2026-11-17T14:00:00.000Z",
"metered": false
}
expiresAt es el fin definitivo, 4 horas después de la apertura. El router debe conectar su túnel en 90 segundos, o la sesión termina (no_dial).
Nuevo enlace de entrada
POST /api/iot/remote-access/sessions/{sessionId} (sin cuerpo) responde 200 { "openUrl": "…" } con un enlace nuevo de un solo uso, por ejemplo cuando el primero caducó sin usarse. Solo quien abrió la sesión recibe uno.
Cerrar una sesión
DELETE /api/iot/remote-access/sessions/{sessionId} termina la sesión de inmediato: la pestaña del navegador deja de funcionar en aproximadamente un segundo y al router se le indica que cierre el túnel. La respuesta es 200 { "session": {...} }. Cerrar una sesión que ya terminó responde igual, sin registrar nada dos veces.
Listar sesiones
GET /api/iot/remote-access/sessions?state=all&deviceId=…&limit=100
| Parámetro | Valores | Por defecto |
|---|---|---|
state | open o all | open |
deviceId | Un id de dispositivo | todos los routers |
limit | 1 o más; se devuelven como máximo 500 filas | 100 |
Los parámetros desconocidos se rechazan con 400. Las sesiones vienen de la más reciente a la más antigua:
{
"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 es PENDING (esperando al router), CONNECTED o CLOSED. closeReason es uno de los códigos de Límites y auditoría del acceso remoto. mine es true para las sesiones abiertas por el titular de la clave. En usage, un límite null significa que su plan no fija ninguno. Las sesiones terminadas se conservan 180 días.
Rechazos
Cada rechazo incluye details.reason.
| Estado | details.reason | code | Mensaje |
|---|---|---|---|
| 404 | device_not_found | NOT_FOUND | Dispositivo no encontrado. |
| 409 | not_claimed | CONFLICT | Rechazado: el dispositivo no es un router con licencia reclamado |
| 409 | unsupported | CONFLICT | Este router todavía no admite el acceso al panel. Actualice su firmware. |
| 409 | device_not_active | CONFLICT | El dispositivo no está activo. |
| 409 | certificate_inactive | CONFLICT | El router no tiene un certificado válido. Vuelva a aprovisionarlo. |
| 409 | offline | CONFLICT | El router está desconectado. |
| 403 | monthly_bytes | QUOTA_EXCEEDED | Se ha agotado la cuota de datos del panel de este mes. (details.limit) |
| 409 | device_busy | CONFLICT | Este router ya tiene 3 sesiones abiertas del panel. Cierre una primero. |
| 403 | tenant_limit | QUOTA_EXCEEDED | Se ha alcanzado el límite de sesiones abiertas del panel de su plan. Cierre una primero. (details.limit, details.current) |
| 409 | opt_in | CONFLICT | El acceso al panel está desactivado en este router. Active «Permitir el acceso al panel desde mi cuenta en la nube» en la página Nube del router. |
| 409 | router_busy | CONFLICT | El router rechazó la sesión: ya tiene el máximo de sesiones de panel que permite. |
| 409 | router_refused | CONFLICT | El router rechazó la sesión del panel. (details.error) |
| 504 | router_unreachable | PROVIDER_UNAVAILABLE | El router no respondió. Inténtelo de nuevo en un momento. |
| 503 | not_configured | PROVIDER_UNAVAILABLE | El acceso al panel no está configurado en esta instalación. |
| 404 | session_not_found | NOT_FOUND | Sesión del panel no encontrada. |
| 409 | session_closed | CONFLICT | Esta sesión del panel ha terminado. |
| 403 | not_opener | FORBIDDEN | Solo quien abrió esta sesión del panel puede entrar en ella. |
Reintente solo router_unreachable y offline, tras una pausa. Para opt_in, alguien en el router debe activar el acceso al panel; no se puede hacer desde Hermetry.
Límites
| Límite | Valor |
|---|---|
| Sesiones abiertas por router | 3 |
| Sesiones abiertas por organización | Valor de su plan (usage.openLimit) |
| Datos del panel por mes | Valor de su plan (usage.monthBytesLimit) |
| Duración de la sesión | 4 horas desde la apertura, sea cual sea la actividad |
| Tiempo de inactividad | 30 minutos sin tráfico |
| Enlace de entrada | Un uso, dentro de 60 segundos |
| El router debe conectarse | En 90 segundos |
| Límite de datos en un enlace móvil | capBytes por sesión |

