Cette page est destinée aux intégrateurs qui ouvrent le panneau web d’un routeur depuis leurs propres outils, par exemple une console de support qui envoie un technicien directement dans le panneau du routeur d’un client. Le fonctionnement des sessions de panneau pour les utilisateurs est décrit dans Accès à distance au panneau d’un routeur ; les limites et les raisons de fin de session se trouvent dans Limites de l’accès à distance et audit.
Les chemins se trouvent sous https://<your host>/tenant/<tenantId>. Les conventions sont décrites dans Bases de l’API REST.
Routes
| Méthode | Chemin | Permission | Fonction |
|---|---|---|---|
| GET | /api/iot/devices/{deviceId}/remote-access | iot_remote_access.panel.open | Indique si une session peut être ouverte sur ce routeur, ainsi que ses sessions ouvertes |
| POST | /api/iot/remote-access/sessions | iot_remote_access.panel.open | Ouvrir une session de panneau |
| POST | /api/iot/remote-access/sessions/{sessionId} | iot_remote_access.panel.open | Un nouveau lien d’accès pour l’ouvreur de la session |
| DELETE | /api/iot/remote-access/sessions/{sessionId} | iot_remote_access.panel.open | Fermer une session |
| GET | /api/iot/remote-access/sessions | iot_remote_access.sessions.read | Les sessions de l’organisation et l’utilisation de ce mois-ci |
Les deux permissions sont par défaut des permissions d’administrateur. La commande qui demande à un routeur d’ouvrir son tunnel ne peut pas être envoyée via l’API Commands (elle répond 403 rpc_method_reserved) ; ces routes sont donc la seule voie, de sorte que chaque session est contrôlée, limitée et auditée.
À qui appartient la session
Une session ouverte avec une clé est ouverte au nom du titulaire de la clé : la liste des sessions affiche le titulaire sous Ouvert par, et le journal d’audit l’enregistre. Seules les requêtes faites au nom de l’ouvreur peuvent obtenir un lien d’accès à la session, de sorte que le titulaire peut aussi y revenir depuis l’application. Tout membre ou toute clé disposant de iot_remote_access.panel.open peut fermer n’importe quelle session de l’organisation.
La session prend fin lorsque le titulaire quitte l’organisation ou que ses accès changent, comme pour une session ouverte dans l’application. Révoquer la clé ne ferme pas les sessions qu’elle a déjà ouvertes : fermez-les avec DELETE lorsque votre programme a terminé.
Avertissement
Le lien d’accès (openUrl) est un identifiant d’authentification. Quiconque l’ouvre en premier, dans les 60 secondes, accède au panneau du routeur sans se connecter à Hermetry. Ne le transmettez qu’à la personne qui en a besoin, par un canal de confiance, et ne l’écrivez jamais dans un journal.
Vérifier d’abord un routeur
GET /api/iot/devices/{deviceId}/remote-access
{ "configured": true, "available": false, "reason": "offline", "metered": false, "open": [] }
reason vaut null lorsqu’une session peut être ouverte, sinon l’une des valeurs not_configured, device_not_found, not_claimed, unsupported, device_not_active, certificate_inactive ou offline (les mêmes motifs que ceux pour lesquels la route d’ouverture refuse). metered vaut true lorsque le routeur est sur sa liaison mobile. open liste les sessions ouvertes du routeur.
Ouvrir une session
POST /api/iot/remote-access/sessions
| Champ | Règle |
|---|---|
deviceId | Obligatoire. L’identifiant de l’appareil routeur |
target | panel (la valeur par défaut et la seule valeur possible) |
confirm | true pour accepter le plafond de données sur une liaison mobile |
Le corps est strict : un champ inconnu entraîne une erreur 400.
Sur une liaison mobile (LTE), le premier appel ne crée rien et répond 200 { "requiresConfirm": "metered", "capBytes": 52428800 } : le nombre d’octets que la session peut transférer avant d’être fermée. Renvoyez le même corps avec "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}'
L’appel attend jusqu’à 15 secondes que le routeur accepte. Il répond ensuite 201 :
{
"sessionId": "dk3v…",
"openUrl": "https://dk3v….<panel domain>/__open?t=…",
"expiresAt": "2026-11-17T14:00:00.000Z",
"metered": false
}
expiresAt est la fin stricte, 4 heures après l’ouverture. Le routeur doit établir son tunnel dans les 90 secondes, faute de quoi la session prend fin (no_dial).
Nouveau lien d’accès
POST /api/iot/remote-access/sessions/{sessionId} (sans corps) répond 200 { "openUrl": "…" } avec un nouveau lien à usage unique, par exemple lorsque le premier a expiré sans être utilisé. Seul l’ouvreur en reçoit un.
Fermer une session
DELETE /api/iot/remote-access/sessions/{sessionId} met fin à la session immédiatement : l’onglet du navigateur cesse de fonctionner en environ une seconde et le routeur est informé de fermer le tunnel. La réponse est 200 { "session": {...} }. Fermer une session déjà terminée donne la même réponse, sans rien enregistrer deux fois.
Lister les sessions
GET /api/iot/remote-access/sessions?state=all&deviceId=…&limit=100
| Paramètre | Valeurs | Par défaut |
|---|---|---|
state | open ou all | open |
deviceId | Un identifiant d’appareil | tous les routeurs |
limit | 1 ou plus ; au plus 500 lignes sont renvoyées | 100 |
Les paramètres inconnus sont refusés avec 400. Les sessions sont classées de la plus récente à la plus ancienne :
{
"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 vaut PENDING (en attente du routeur), CONNECTED ou CLOSED. closeReason est l’un des codes listés dans Limites de l’accès à distance et audit. mine vaut true pour les sessions ouvertes par le titulaire de la clé. Dans usage, une limite null signifie que votre offre n’en fixe aucune. Les sessions terminées sont conservées 180 jours.
Refus
Chaque refus porte details.reason.
| Statut | details.reason | code | Message |
|---|---|---|---|
| 404 | device_not_found | NOT_FOUND | Appareil introuvable. |
| 409 | not_claimed | CONFLICT | Refusé : l’appareil n’est pas un routeur sous licence rattaché |
| 409 | unsupported | CONFLICT | Ce routeur ne prend pas encore en charge l’accès au panneau. Mettez à jour son micrologiciel. |
| 409 | device_not_active | CONFLICT | L’appareil n’est pas actif. |
| 409 | certificate_inactive | CONFLICT | Le routeur n’a pas de certificat valide. Provisionnez-le à nouveau. |
| 409 | offline | CONFLICT | Le routeur est hors ligne. |
| 403 | monthly_bytes | QUOTA_EXCEEDED | Le volume mensuel de données du panneau est épuisé. (details.limit) |
| 409 | device_busy | CONFLICT | Ce routeur a déjà 3 sessions de panneau ouvertes. Fermez-en une d’abord. |
| 403 | tenant_limit | QUOTA_EXCEEDED | La limite de sessions de panneau ouvertes de votre offre est atteinte. Fermez-en une d’abord. (details.limit, details.current) |
| 409 | opt_in | CONFLICT | L’accès au panneau est désactivé sur ce routeur. Activez « Autoriser l’accès au panneau depuis mon compte cloud » sur la page Cloud du routeur. |
| 409 | router_busy | CONFLICT | Le routeur a refusé : il a déjà le nombre maximal de sessions de panneau qu’il autorise. |
| 409 | router_refused | CONFLICT | Le routeur a refusé la session de panneau. (details.error) |
| 504 | router_unreachable | PROVIDER_UNAVAILABLE | Le routeur n’a pas répondu. Réessayez dans un instant. |
| 503 | not_configured | PROVIDER_UNAVAILABLE | L’accès au panneau n’est pas configuré sur cette installation. |
| 404 | session_not_found | NOT_FOUND | Session de panneau introuvable. |
| 409 | session_closed | CONFLICT | Cette session de panneau est terminée. |
| 403 | not_opener | FORBIDDEN | Seule la personne qui a ouvert cette session de panneau peut y accéder. |
Ne réessayez que router_unreachable et offline, après une pause. Pour opt_in, quelqu’un sur place doit activer l’accès au panneau ; cela ne peut pas se faire depuis Hermetry.
Limites
| Limite | Valeur |
|---|---|
| Sessions ouvertes par routeur | 3 |
| Sessions ouvertes par organisation | Valeur de votre offre (usage.openLimit) |
| Données du panneau par mois | Valeur de votre offre (usage.monthBytesLimit) |
| Durée de session | 4 heures après l’ouverture, quelle que soit l’activité |
| Délai d’inactivité | 30 minutes sans trafic |
| Lien d’accès | Un usage, dans les 60 secondes |
| Connexion du routeur | Dans les 90 secondes |
| Plafond de données sur une liaison mobile | capBytes par session |

