Aller au contenu
Localtonet Localtonet Tableau de bord

API REST de Localtonet

Aide pour cette page
Sur cette page 8 sections
  1. Référence interactive
  2. Avant de commencer
  3. URL de base et authentification
  4. Conventions
  5. Erreurs
  6. Limites de débit
  7. Exemples
  8. Lister vos tunnels
  9. Créer un tunnel HTTP avec un sous-domaine aléatoire
  10. Démarrer le tunnel
  11. Groupes de points de terminaison
  12. Tunnels
  13. Opérations de tunnel en masse
  14. Configuration du tunnel
  15. AuthTokens
  16. Groupes de jetons
  17. Serveurs
  18. Fournisseurs SSO
  19. Accès VPN
  20. Dépannage
  21. Pages associées

L'API REST v2 fait pour les tunnels ce que fait le tableau de bord : les créer, les démarrer, les arrêter, les supprimer et les configurer, ainsi que gérer les AuthTokens, les groupes de jetons et les fournisseurs SSO. Vous authentifiez chaque requête avec votre clé API.

Référence interactive #

Chaque point de terminaison, avec ses modèles de requête et de réponse et un formulaire pour l'essayer, se trouve dans la référence interactive :

  • localtonet.com/api : l'API v2, la version actuelle. Vous y accédez aussi avec le bouton Interface API du tableau de bord.
  • localtonet.com/api/v1 : l'API v1, conservée pour les intégrations existantes. Utilisez la v2 pour tout nouveau développement.

Cette page présente les conventions et un aperçu des groupes de points de terminaison. Pour connaître les champs exacts d'une requête, ouvrez le point de terminaison dans la référence.

Avant de commencer #

  • Votre clé API. Ouvrez le Tableau de bord et utilisez Copier dans la carte Clé API. Consultez Compte et sécurité.
  • Pour créer un tunnel : un AuthToken de l'appareil qui exécutera le tunnel, et un client Localtonet connecté avec ce jeton. Consultez AuthTokens.

Gardez votre clé API privée. Toute personne qui la possède peut créer, modifier et supprimer vos tunnels et vos jetons. Modifier dans la carte Clé API crée une nouvelle clé et invalide l'ancienne.

URL de base et authentification #

Tous les points de terminaison v2 commencent par :

URL de base
https://localtonet.com/api/v2

Envoyez la clé API comme jeton Bearer dans l'en-tête Authorization de chaque requête :

HTTP
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>

Une clé API copiée dans un tableau de bord d'équipe liste vos AuthTokens et vos tunnels de cette équipe ; la clé de votre propre compte liste les AuthTokens qui n'appartiennent à aucune équipe.

Conventions #

SujetComportement de l'API
FormatLes corps de requête et de réponse sont au format JSON. Envoyez Content-Type: application/json avec un corps.
ID du tunnelLe tunnelId dans un chemin est l'id numérique du tunnel, tel que renvoyé par les points de terminaison de liste et de création.
AuthToken dans un chemin{token} est la chaîne de l'AuthToken elle-même.
Codes de réussite200 avec un corps pour les lectures, 201 pour la plupart des créations (les points de terminaison de création de tunnel renvoient le nouveau tunnel), 204 sans corps pour la plupart des actions et des mises à jour. La référence indique la réponse de chaque point de terminaison.
Points de terminaison en masseLes chemins qui contiennent /bulk/ acceptent un tableau JSON et jusqu'à 100 éléments par requête (/tunnels/bulk/protocol-type : jusqu'à 500).
Nouveaux tunnelsUn tunnel que vous créez n'est pas encore en cours d'exécution. Démarrez-le avec l'action de démarrage. Seuls les points de terminaison proxy/with-detail peuvent démarrer le tunnel dans le même appel, avec isStartAfterCreate.

Erreurs #

StatutSignificationCorps
400Le corps de la requête n'est pas valide, ou l'opération a été refusée, par exemple en raison d'une limite de votre offre.Pour la plupart des points de terminaison, un objet problem en JSON ; title contient le message. Les erreurs de validation et celles des points de terminaison en masse sont listées sous errors.
401La clé API est absente ou invalide.Aucun message spécifique
403, 409Renvoyé par certains points de terminaison de configuration de tunnel et d'accès VPN lorsque la modification n'est pas autorisée ou entre en conflit avec la configuration actuelle.Un objet problem avec le message dans title.
404Le tunnel ou l'objet est introuvable ou ne vous appartient pas.Vide ou un objet problem
429Trop de requêtes.Consultez les limites de débit ci-dessous.

Limites de débit #

Les requêtes sont soumises à une limite de débit. Une requête qui dépasse la limite reçoit la réponse 429 Too Many Requests. Patientez et renvoyez-la ; utilisez les points de terminaison en masse plutôt que de nombreux appels individuels.

Exemples #

Remplacez <YOUR_API_KEY> par votre clé API et <YOUR_TOKEN> par l'AuthToken de l'appareil.

Lister vos tunnels #

Bash
curl https://localtonet.com/api/v2/tunnels \
  -H "Authorization: Bearer <YOUR_API_KEY>"

La réponse est un tableau JSON avec un objet par tunnel. Parmi ses champs figurent id, title, url (l'adresse publique), protocolType, authToken, serverId, clientIp et clientPort (la cible locale), status et connectionStatus. Si vous n'avez encore aucun tunnel, la réponse est 404 au lieu d'un tableau vide.

Créer un tunnel HTTP avec un sous-domaine aléatoire #

Commencez par obtenir le code du serveur que vous voulez utiliser :

Bash
curl https://localtonet.com/api/v2/servers \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Chaque entrée comporte un serverCode, un serverName et un serverDomain. Créez ensuite le tunnel. Cet exemple redirige vers une application web sur le port 3000 de l'appareil :

Bash
curl -X POST https://localtonet.com/api/v2/tunnels/http/random-subdomain \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "authToken": "<YOUR_TOKEN>",
    "serverCode": "<SERVER_CODE>",
    "protocolType": 1,
    "ip": "127.0.0.1",
    "port": 3000
  }'
ChampSignificationValeurs
authTokenL'AuthToken de l'appareil qui exécute le tunnel.Obligatoire
serverCodeLe serveur, obtenu avec GET /servers.Obligatoire
protocolTypeLe type de tunnel.1 HTTP, 5 File Server, 24 MCP Gateway
ipL'adresse IP locale vers laquelle le tunnel redirige.Une adresse IP valide, par exemple 127.0.0.1
portLe port local.1 à 65534
pathLe dossier local à partager.Obligatoire pour File Server uniquement

La réponse est 201 Created avec le nouveau tunnel. Notez son id et son url.

Démarrer le tunnel #

Bash
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
  -H "Authorization: Bearer <YOUR_API_KEY>"

La réponse est 204 No Content. Le tunnel devient accessible à son url lorsque le client de l'appareil est connecté. Arrêtez-le de nouveau avec /actions/stop.

Groupes de points de terminaison #

Tous les chemins ci-dessous sont relatifs à https://localtonet.com/api/v2.

Tunnels #

MéthodeCheminUsage
GET/tunnelsLister tous vos tunnels.
GET/tunnels/{tunnelId}Obtenir un tunnel.
POST/tunnels/http/random-subdomainCréer un tunnel HTTP, Serveur de fichiers ou Passerelle MCP avec un sous-domaine aléatoire.
POST/tunnels/http/custom-subdomainEn créer un avec un sous-domaine de votre choix.
POST/tunnels/http/custom-domainEn créer un sur votre propre domaine.
POST/tunnels/tcp-udpCréer un tunnel TCP, UDP ou TCP et UDP combinés.
POST/tunnels/proxyCréer un tunnel proxy HTTP, SOCKS5, Shadowsocks ou VLESS.
POST/tunnels/proxy/with-detailCréer un tunnel proxy et renvoyer ses détails de connexion complets.
POST/tunnels/shared-proxyCréer un tunnel proxy partagé (rotatif).
POST/tunnels/{tunnelId}/actions/startDémarrer un tunnel.
POST/tunnels/{tunnelId}/actions/stopArrêter un tunnel.
DELETE/tunnels/{tunnelId}Supprimer définitivement un tunnel.
PATCH/tunnels/{tunnelId}/titleModifier le titre.
PATCH/tunnels/{tunnelId}/local-ipModifier l'adresse IP locale.
PATCH/tunnels/{tunnelId}/local-portModifier le port local.
PATCH/tunnels/{tunnelId}/port-reservedActiver ou désactiver la réservation de port d'un tunnel TCP/UDP.
PATCH/tunnels/{tunnelId}/legacy-connectActiver ou désactiver le mode de connexion hérité.
PATCH/tunnels/{tunnelId}/protocol-typeModifier le protocole proxy d'un tunnel proxy.
GET/tunnels/{tunnelId}/request-logsJournaux des requêtes HTTP récentes d'un tunnel HTTP ou Serveur de fichiers.

Opérations de tunnel en masse #

MéthodeCheminUsage
POST/tunnels/bulk/http/random-subdomainCréer plusieurs tunnels HTTP avec des sous-domaines aléatoires.
POST/tunnels/bulk/http/custom-subdomainEn créer plusieurs avec des sous-domaines personnalisés.
POST/tunnels/bulk/http/custom-domainEn créer plusieurs sur des domaines personnalisés.
POST/tunnels/bulk/tcp-udpCréer plusieurs tunnels TCP/UDP.
POST/tunnels/bulk/proxyCréer plusieurs tunnels proxy.
POST/tunnels/bulk/proxy/with-detailCréer plusieurs tunnels proxy et renvoyer leurs détails de connexion.
POST/tunnels/bulk/shared-proxyCréer plusieurs tunnels proxy partagés (rotatifs).
POST/tunnels/bulk/actions/startDémarrer plusieurs tunnels. Corps : un tableau d'ID de tunnel, par exemple [123, 456].
POST/tunnels/bulk/actions/stopArrêter plusieurs tunnels. Corps : un tableau d'ID de tunnel.
DELETE/tunnels/bulkSupprimer plusieurs tunnels. Corps : un tableau d'ID de tunnel.
PATCH/tunnels/bulk/protocol-typeModifier le protocole proxy de plusieurs tunnels proxy.

Configuration du tunnel #

Ces points de terminaison modifient les paramètres d'un seul tunnel. Ils commencent tous par /tunnels/{tunnelId}. Le rôle de chaque paramètre est décrit dans la Référence des paramètres.

MéthodesChemin après /tunnels/{tunnelId}Usage
GET, POST, PATCH, DELETE/ip-restrictionsLister, ajouter, définir le mode d'autorisation ou de refus, ou supprimer toutes les restrictions d'IP. Supprimez-en une avec /ip-restrictions/{restrictionId}.
GET, POST, PATCH, DELETE/access-controlsLa même chose pour les contrôles d'accès par chemin d'URL. Supprimez-en un avec /access-controls/{controlId}.
GET, PATCH/headersEn-têtes HTTP personnalisés.
GET, PATCH/authenticationAuthentification HTTP Basic.
GET, PATCH/expirationDate d'expiration du tunnel.
GET, PATCH/server-portPort côté serveur d'un tunnel TCP/UDP.
GET, PATCH/http-timeoutDélai d'expiration des requêtes HTTP.
GET, PATCH/rate-limitLimite de vitesse.
GET, PATCH/bandwidth-limitLimite totale de transfert de données.
GET/bandwidth-usageUtilisation actuelle de la bande passante. Réinitialisez le compteur avec POST /bandwidth-usage/reset.
GET, PATCH/argumentsArguments de ligne de commande personnalisés pour le tunnel.
GET, POST/shared-proxy-clientsLister ou ajouter des clients d'un tunnel proxy partagé (rotatif). Modifiez ou supprimez-en un avec PATCH ou DELETE /shared-proxy-clients/{clientId}.
GET/advanced-settingsTous les paramètres avancés du tunnel en une seule réponse.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3Lire ou basculer un paramètre avancé.
PATCH/ssl-streamBasculer le paramètre de flux SSL.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessLire ou modifier une valeur.
GET, PUT/token-groupsLes groupes de jetons affectés au tunnel.
GET, PATCH/serverLe serveur du tunnel.

AuthTokens #

MéthodeCheminUsage
GET/auth-tokensLister vos AuthTokens.
GET/auth-tokens/detailLister vos AuthTokens avec leurs détails.
GET/auth-tokens/{token}Détails d'un AuthToken.
POST/auth-tokensCréer un AuthToken.
DELETE/auth-tokens/{token}Supprimer un AuthToken.
GET/auth-tokens/{token}/tunnelsLes tunnels d'un AuthToken.
GET/auth-tokens/{token}/ip-historyHistorique des changements d'adresse IP publique de l'appareil.
GET, PATCH/auth-tokens/{token}/airplane-mode-settingsParamètres d'automatisation du mode avion.
POST/auth-tokens/{token}/change-ip-links/{airplaneModeSettingId}Ajouter un lien de changement d'IP.
DELETE/auth-tokens/{token}/change-ip-links/{id}Supprimer un lien de changement d'IP.
POST/auth-tokens/{token}/restart-device-links/{airplaneModeSettingId}Ajouter un lien de redémarrage de l'appareil.
DELETE/auth-tokens/{token}/restart-device-links/{id}Supprimer un lien de redémarrage de l'appareil.
GET, PATCH/auth-tokens/{token}/argumentsLes arguments du client enregistrés sur l'AuthToken.

Groupes de jetons #

MéthodeCheminUsage
GET/token-groupsLister vos groupes de jetons.
GET/token-groups/{id}Obtenir un groupe de jetons.
POST/token-groupsCréer un groupe de jetons.
DELETE/token-groups/{id}Supprimer un groupe de jetons.
POST/token-groups/{id}/auth-tokensAjouter un AuthToken au groupe.
DELETE/token-groups/{id}/auth-tokens/{tokenId}Retirer un AuthToken du groupe.

Serveurs #

MéthodeCheminUsage
GET/serversLister les serveurs sur lesquels vous pouvez créer des tunnels, avec le serverCode à utiliser dans les requêtes de création.

Fournisseurs SSO #

MéthodeCheminUsage
GET/sso-providersLister vos fournisseurs SSO.
GET/sso-providers/default-endpointsPoints de terminaison par défaut pour un type de fournisseur SSO.
POST/sso-providersCréer ou mettre à jour un fournisseur SSO.
DELETE/sso-providers/{id}Supprimer un fournisseur SSO.
GET/sso-providers/tunnel/{tunnelId}Les fournisseurs SSO configurés pour un tunnel. Ici, tunnelId est le GUID du tunnel (guidId).
PUT/sso-providers/tunnel/{tunnelId}Enregistrer les fournisseurs SSO d'un tunnel.

Consultez Authentification unique (SSO) pour savoir à quoi servent les fournisseurs.

Accès VPN #

L'accès VPN fournit un profil d'appareil WireGuard ou OpenVPN sur un tunnel proxy ; tout le trafic de cet appareil sort par le proxy. Ces points de terminaison commencent par /tunnels/{tunnelId}/vpn-access.

MéthodeChemin après /tunnels/{tunnelId}/vpn-accessUsage
GET(aucun)Lister les appareils VPN du tunnel.
POST(aucun)Créer un appareil VPN.
DELETE/{peerId}Supprimer (révoquer) un appareil VPN.
POST/{peerId}/regenerateRégénérer les clés d'un appareil VPN.
GET/{peerId}/configTélécharger le fichier de configuration d'un appareil VPN.
GET/{peerId}/qrCode QR de la configuration d'un appareil WireGuard.
GET/{peerId}/credentialsNom d'utilisateur et mot de passe d'un appareil OpenVPN.

Dépannage #

Chaque requête renvoie 401

Vérifiez l'en-tête : il doit être Authorization: Bearer suivi d'un espace et de la clé, sans guillemets autour de la clé. Si vous avez sélectionné Modifier dans la carte Clé API, l'ancienne clé ne fonctionne plus ; copiez la nouvelle.

Je ne vois pas les AuthTokens de mon équipe

Vous utilisez la clé API de votre propre compte. Passez au tableau de bord de l'équipe et copiez-y la clé API.

Le tunnel a été créé mais son adresse ne répond pas

Un nouveau tunnel est arrêté. Appelez POST /tunnels/{tunnelId}/actions/start et vérifiez que le client Localtonet de l'appareil s'exécute avec l'AuthToken que vous avez utilisé.

J'obtiens 429 Too Many Requests

Les requêtes sont soumises à une limite de débit. Patientez, puis renvoyez la requête, et remplacez les boucles d'appels individuels par une seule requête en masse.

Support