API REST de Localtonet
Sur cette page 8 sections
- Référence interactive
- Avant de commencer
- URL de base et authentification
- Conventions
- Erreurs
- Limites de débit
- Exemples
- Lister vos tunnels
- Créer un tunnel HTTP avec un sous-domaine aléatoire
- Démarrer le tunnel
- Groupes de points de terminaison
- Tunnels
- Opérations de tunnel en masse
- Configuration du tunnel
- AuthTokens
- Groupes de jetons
- Serveurs
- Fournisseurs SSO
- Accès VPN
- Dépannage
- 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 :
https://localtonet.com/api/v2Envoyez la clé API comme jeton Bearer dans l'en-tête Authorization de chaque requête :
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 #
| Sujet | Comportement de l'API |
|---|---|
| Format | Les corps de requête et de réponse sont au format JSON. Envoyez Content-Type: application/json avec un corps. |
| ID du tunnel | Le 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éussite | 200 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 masse | Les chemins qui contiennent /bulk/ acceptent un tableau JSON et jusqu'à 100 éléments par requête (/tunnels/bulk/protocol-type : jusqu'à 500). |
| Nouveaux tunnels | Un 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 #
| Statut | Signification | Corps |
|---|---|---|
400 | Le 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. |
401 | La clé API est absente ou invalide. | Aucun message spécifique |
403, 409 | Renvoyé 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. |
404 | Le tunnel ou l'objet est introuvable ou ne vous appartient pas. | Vide ou un objet problem |
429 | Trop 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 #
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 :
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 :
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
}'| Champ | Signification | Valeurs |
|---|---|---|
authToken | L'AuthToken de l'appareil qui exécute le tunnel. | Obligatoire |
serverCode | Le serveur, obtenu avec GET /servers. | Obligatoire |
protocolType | Le type de tunnel. | 1 HTTP, 5 File Server, 24 MCP Gateway |
ip | L'adresse IP locale vers laquelle le tunnel redirige. | Une adresse IP valide, par exemple 127.0.0.1 |
port | Le port local. | 1 à 65534 |
path | Le 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 #
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éthode | Chemin | Usage |
|---|---|---|
| GET | /tunnels | Lister tous vos tunnels. |
| GET | /tunnels/{tunnelId} | Obtenir un tunnel. |
| POST | /tunnels/http/random-subdomain | Créer un tunnel HTTP, Serveur de fichiers ou Passerelle MCP avec un sous-domaine aléatoire. |
| POST | /tunnels/http/custom-subdomain | En créer un avec un sous-domaine de votre choix. |
| POST | /tunnels/http/custom-domain | En créer un sur votre propre domaine. |
| POST | /tunnels/tcp-udp | Créer un tunnel TCP, UDP ou TCP et UDP combinés. |
| POST | /tunnels/proxy | Créer un tunnel proxy HTTP, SOCKS5, Shadowsocks ou VLESS. |
| POST | /tunnels/proxy/with-detail | Créer un tunnel proxy et renvoyer ses détails de connexion complets. |
| POST | /tunnels/shared-proxy | Créer un tunnel proxy partagé (rotatif). |
| POST | /tunnels/{tunnelId}/actions/start | Démarrer un tunnel. |
| POST | /tunnels/{tunnelId}/actions/stop | Arrêter un tunnel. |
| DELETE | /tunnels/{tunnelId} | Supprimer définitivement un tunnel. |
| PATCH | /tunnels/{tunnelId}/title | Modifier le titre. |
| PATCH | /tunnels/{tunnelId}/local-ip | Modifier l'adresse IP locale. |
| PATCH | /tunnels/{tunnelId}/local-port | Modifier le port local. |
| PATCH | /tunnels/{tunnelId}/port-reserved | Activer ou désactiver la réservation de port d'un tunnel TCP/UDP. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | Activer ou désactiver le mode de connexion hérité. |
| PATCH | /tunnels/{tunnelId}/protocol-type | Modifier le protocole proxy d'un tunnel proxy. |
| GET | /tunnels/{tunnelId}/request-logs | Journaux des requêtes HTTP récentes d'un tunnel HTTP ou Serveur de fichiers. |
Opérations de tunnel en masse #
| Méthode | Chemin | Usage |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | Créer plusieurs tunnels HTTP avec des sous-domaines aléatoires. |
| POST | /tunnels/bulk/http/custom-subdomain | En créer plusieurs avec des sous-domaines personnalisés. |
| POST | /tunnels/bulk/http/custom-domain | En créer plusieurs sur des domaines personnalisés. |
| POST | /tunnels/bulk/tcp-udp | Créer plusieurs tunnels TCP/UDP. |
| POST | /tunnels/bulk/proxy | Créer plusieurs tunnels proxy. |
| POST | /tunnels/bulk/proxy/with-detail | Créer plusieurs tunnels proxy et renvoyer leurs détails de connexion. |
| POST | /tunnels/bulk/shared-proxy | Créer plusieurs tunnels proxy partagés (rotatifs). |
| POST | /tunnels/bulk/actions/start | Démarrer plusieurs tunnels. Corps : un tableau d'ID de tunnel, par exemple [123, 456]. |
| POST | /tunnels/bulk/actions/stop | Arrêter plusieurs tunnels. Corps : un tableau d'ID de tunnel. |
| DELETE | /tunnels/bulk | Supprimer plusieurs tunnels. Corps : un tableau d'ID de tunnel. |
| PATCH | /tunnels/bulk/protocol-type | Modifier 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éthodes | Chemin après /tunnels/{tunnelId} | Usage |
|---|---|---|
| GET, POST, PATCH, DELETE | /ip-restrictions | Lister, 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-controls | La même chose pour les contrôles d'accès par chemin d'URL. Supprimez-en un avec /access-controls/{controlId}. |
| GET, PATCH | /headers | En-têtes HTTP personnalisés. |
| GET, PATCH | /authentication | Authentification HTTP Basic. |
| GET, PATCH | /expiration | Date d'expiration du tunnel. |
| GET, PATCH | /server-port | Port côté serveur d'un tunnel TCP/UDP. |
| GET, PATCH | /http-timeout | Délai d'expiration des requêtes HTTP. |
| GET, PATCH | /rate-limit | Limite de vitesse. |
| GET, PATCH | /bandwidth-limit | Limite totale de transfert de données. |
| GET | /bandwidth-usage | Utilisation actuelle de la bande passante. Réinitialisez le compteur avec POST /bandwidth-usage/reset. |
| GET, PATCH | /arguments | Arguments de ligne de commande personnalisés pour le tunnel. |
| GET, POST | /shared-proxy-clients | Lister 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-settings | Tous les paramètres avancés du tunnel en une seule réponse. |
| GET, PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | Lire ou basculer un paramètre avancé. |
| PATCH | /ssl-stream | Basculer le paramètre de flux SSL. |
| GET, PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | Lire ou modifier une valeur. |
| GET, PUT | /token-groups | Les groupes de jetons affectés au tunnel. |
| GET, PATCH | /server | Le serveur du tunnel. |
AuthTokens #
| Méthode | Chemin | Usage |
|---|---|---|
| GET | /auth-tokens | Lister vos AuthTokens. |
| GET | /auth-tokens/detail | Lister vos AuthTokens avec leurs détails. |
| GET | /auth-tokens/{token} | Détails d'un AuthToken. |
| POST | /auth-tokens | Créer un AuthToken. |
| DELETE | /auth-tokens/{token} | Supprimer un AuthToken. |
| GET | /auth-tokens/{token}/tunnels | Les tunnels d'un AuthToken. |
| GET | /auth-tokens/{token}/ip-history | Historique des changements d'adresse IP publique de l'appareil. |
| GET, PATCH | /auth-tokens/{token}/airplane-mode-settings | Paramè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}/arguments | Les arguments du client enregistrés sur l'AuthToken. |
Groupes de jetons #
| Méthode | Chemin | Usage |
|---|---|---|
| GET | /token-groups | Lister vos groupes de jetons. |
| GET | /token-groups/{id} | Obtenir un groupe de jetons. |
| POST | /token-groups | Créer un groupe de jetons. |
| DELETE | /token-groups/{id} | Supprimer un groupe de jetons. |
| POST | /token-groups/{id}/auth-tokens | Ajouter un AuthToken au groupe. |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | Retirer un AuthToken du groupe. |
Serveurs #
| Méthode | Chemin | Usage |
|---|---|---|
| GET | /servers | Lister les serveurs sur lesquels vous pouvez créer des tunnels, avec le serverCode à utiliser dans les requêtes de création. |
Fournisseurs SSO #
| Méthode | Chemin | Usage |
|---|---|---|
| GET | /sso-providers | Lister vos fournisseurs SSO. |
| GET | /sso-providers/default-endpoints | Points de terminaison par défaut pour un type de fournisseur SSO. |
| POST | /sso-providers | Cré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éthode | Chemin après /tunnels/{tunnelId}/vpn-access | Usage |
|---|---|---|
| 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}/regenerate | Régénérer les clés d'un appareil VPN. |
| GET | /{peerId}/config | Télécharger le fichier de configuration d'un appareil VPN. |
| GET | /{peerId}/qr | Code QR de la configuration d'un appareil WireGuard. |
| GET | /{peerId}/credentials | Nom 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.