Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

API d’accès à distance

Ouvrir, reprendre, fermer et lister les sessions du panneau des routeurs sous licence revendiqués depuis un programme, avec chaque refus et chaque limite.

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éthodeCheminPermissionFonction
GET/api/iot/devices/{deviceId}/remote-accessiot_remote_access.panel.openIndique si une session peut être ouverte sur ce routeur, ainsi que ses sessions ouvertes
POST/api/iot/remote-access/sessionsiot_remote_access.panel.openOuvrir une session de panneau
POST/api/iot/remote-access/sessions/{sessionId}iot_remote_access.panel.openUn nouveau lien d’accès pour l’ouvreur de la session
DELETE/api/iot/remote-access/sessions/{sessionId}iot_remote_access.panel.openFermer une session
GET/api/iot/remote-access/sessionsiot_remote_access.sessions.readLes 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

ChampRègle
deviceIdObligatoire. L’identifiant de l’appareil routeur
targetpanel (la valeur par défaut et la seule valeur possible)
confirmtrue 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ètreValeursPar défaut
stateopen ou allopen
deviceIdUn identifiant d’appareiltous les routeurs
limit1 ou plus ; au plus 500 lignes sont renvoyées100

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.

Statutdetails.reasoncodeMessage
404device_not_foundNOT_FOUNDAppareil introuvable.
409not_claimedCONFLICTRefusé : l’appareil n’est pas un routeur sous licence rattaché
409unsupportedCONFLICTCe routeur ne prend pas encore en charge l’accès au panneau. Mettez à jour son micrologiciel.
409device_not_activeCONFLICTL’appareil n’est pas actif.
409certificate_inactiveCONFLICTLe routeur n’a pas de certificat valide. Provisionnez-le à nouveau.
409offlineCONFLICTLe routeur est hors ligne.
403monthly_bytesQUOTA_EXCEEDEDLe volume mensuel de données du panneau est épuisé. (details.limit)
409device_busyCONFLICTCe routeur a déjà 3 sessions de panneau ouvertes. Fermez-en une d’abord.
403tenant_limitQUOTA_EXCEEDEDLa limite de sessions de panneau ouvertes de votre offre est atteinte. Fermez-en une d’abord. (details.limit, details.current)
409opt_inCONFLICTL’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.
409router_busyCONFLICTLe routeur a refusé : il a déjà le nombre maximal de sessions de panneau qu’il autorise.
409router_refusedCONFLICTLe routeur a refusé la session de panneau. (details.error)
504router_unreachablePROVIDER_UNAVAILABLELe routeur n’a pas répondu. Réessayez dans un instant.
503not_configuredPROVIDER_UNAVAILABLEL’accès au panneau n’est pas configuré sur cette installation.
404session_not_foundNOT_FOUNDSession de panneau introuvable.
409session_closedCONFLICTCette session de panneau est terminée.
403not_openerFORBIDDENSeule 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

LimiteValeur
Sessions ouvertes par routeur3
Sessions ouvertes par organisationValeur de votre offre (usage.openLimit)
Données du panneau par moisValeur de votre offre (usage.monthBytesLimit)
Durée de session4 heures après l’ouverture, quelle que soit l’activité
Délai d’inactivité30 minutes sans trafic
Lien d’accèsUn usage, dans les 60 secondes
Connexion du routeurDans les 90 secondes
Plafond de données sur une liaison mobilecapBytes par session