Localtonet REST API
Op deze pagina 8 secties
- Interactieve referentie
- Voordat je begint
- Basis-URL en authenticatie
- Conventies
- Fouten
- Limieten
- Voorbeelden
- Je tunnels weergeven
- Een HTTP-tunnel met een willekeurig subdomein aanmaken
- Start de tunnel
- Eindpuntgroepen
- Tunnels
- Bulkbewerkingen voor tunnels
- Tunnelconfiguratie
- AuthTokens
- Tokengroepen
- Servers
- SSO-providers
- VPN-toegang
- Probleemoplossing
- Gerelateerde pagina's
De REST API v2 doet voor tunnels wat het dashboard doet: ze aanmaken, starten, stoppen, verwijderen en configureren, en AuthTokens, tokengroepen en SSO-providers beheren. Je authenticeert elk verzoek met je API-sleutel.
Interactieve referentie #
Elk eindpunt, met de request- en responsemodellen en een formulier om het uit te proberen, staat in de interactieve referentie:
- localtonet.com/api: API v2, de huidige versie. Je bereikt hem ook met de knop API-UI op het dashboard.
- localtonet.com/api/v1: API v1, bewaard voor bestaande integraties. Gebruik v2 voor nieuw werk.
Deze pagina geeft je de conventies en een overzicht van de eindpuntgroepen. Open het eindpunt in de referentie voor de exacte velden van een verzoek.
Voordat je begint #
- Je API-sleutel. Open het Dashboard en gebruik Kopiëren in de kaart API-sleutel. Zie Account en beveiliging.
- Voor het aanmaken van tunnels: een AuthToken van het apparaat dat de tunnel gaat draaien, en een Localtonet-client die met dat token is verbonden. Zie AuthTokens.
Houd je API-sleutel privé. Wie hem heeft, kan je tunnels en tokens aanmaken, wijzigen en verwijderen. Wijzigen in de kaart API-sleutel maakt een nieuwe sleutel aan en maakt de oude ongeldig.
Basis-URL en authenticatie #
Alle v2-eindpunten beginnen met:
https://localtonet.com/api/v2Stuur de API-sleutel als Bearer-token mee in de Authorization-header van elk verzoek:
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>Een API-sleutel die in een teamdashboard is gekopieerd, toont je AuthTokens en tunnels in dat team; de sleutel van je eigen account toont de AuthTokens die bij geen enkel team horen.
Conventies #
| Onderwerp | Hoe de API zich gedraagt |
|---|---|
| Formaat | Request- en responsebodies zijn JSON. Stuur Content-Type: application/json mee met een body. |
| Tunnel-ID | De tunnelId in een pad is de numerieke id van de tunnel, zoals die door de lijst- en aanmaakeindpunten wordt teruggegeven. |
| AuthToken in een pad | {token} is de AuthToken-string zelf. |
| Succescodes | 200 met een body voor leesacties, 201 voor de meeste aanmaakacties (de eindpunten voor het aanmaken van tunnels geven de nieuwe tunnel terug), 204 zonder body voor de meeste acties en updates. De referentie toont het antwoord van elk eindpunt. |
| Bulk-eindpunten | Paden die /bulk/ bevatten, nemen een JSON-array aan en accepteren maximaal 100 items per verzoek (/tunnels/bulk/protocol-type: maximaal 500). |
| Nieuwe tunnels | Een tunnel die je aanmaakt, draait nog niet. Start hem met de startactie. Alleen de proxy/with-detail-eindpunten kunnen de tunnel in dezelfde aanroep starten, met isStartAfterCreate. |
Fouten #
| Status | Betekenis | Body |
|---|---|---|
400 | De request-body is ongeldig, of de bewerking is geweigerd, bijvoorbeeld vanwege een limiet van je abonnement. | Bij de meeste eindpunten een probleemobject in JSON; title bevat het bericht. Validatiefouten en de fouten van bulk-eindpunten staan onder errors. |
401 | De API-sleutel ontbreekt of is ongeldig. | Geen specifiek bericht |
403, 409 | Wordt door sommige eindpunten voor tunnelconfiguratie en VPN-toegang teruggegeven wanneer de wijziging niet is toegestaan of in conflict is met de huidige configuratie. | Een probleemobject met het bericht in title. |
404 | De tunnel of het object is niet gevonden of is niet van jou. | Leeg of een probleemobject |
429 | Te veel verzoeken. | Zie de limieten hieronder. |
Limieten #
Verzoeken zijn aan een limiet gebonden. Een verzoek boven de limiet wordt beantwoord met 429 Too Many Requests. Wacht en stuur het opnieuw; gebruik de bulk-eindpunten in plaats van veel losse aanroepen.
Voorbeelden #
Vervang <YOUR_API_KEY> door je API-sleutel en <YOUR_TOKEN> door de AuthToken van het apparaat.
Je tunnels weergeven #
curl https://localtonet.com/api/v2/tunnels \
-H "Authorization: Bearer <YOUR_API_KEY>"Het antwoord is een JSON-array met één object per tunnel. Tot de velden behoren id, title, url (het openbare adres), protocolType, authToken, serverId, clientIp en clientPort (het lokale doel), status en connectionStatus. Heb je nog geen tunnels, dan is het antwoord 404 in plaats van een lege array.
Een HTTP-tunnel met een willekeurig subdomein aanmaken #
Haal eerst de code op van de server die je wilt gebruiken:
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"Elk item heeft een serverCode, een serverName en een serverDomain. Maak daarna de tunnel aan. Dit voorbeeld stuurt door naar een webapp op poort 3000 van het apparaat:
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
}'| Veld | Betekenis | Waarden |
|---|---|---|
authToken | De AuthToken van het apparaat dat de tunnel draait. | Vereist |
serverCode | De server, uit GET /servers. | Vereist |
protocolType | Het tunneltype. | 1 HTTP, 5 File Server, 24 MCP Gateway |
ip | Het lokale IP-adres waarnaar de tunnel doorstuurt. | Een geldig IP-adres, bijvoorbeeld 127.0.0.1 |
port | De lokale poort. | 1 tot 65534 |
path | De lokale map die je deelt. | Alleen vereist voor File Server |
Het antwoord is 201 Created met de nieuwe tunnel. Noteer de id en url ervan.
Start de tunnel #
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
-H "Authorization: Bearer <YOUR_API_KEY>"Het antwoord is 204 No Content. De tunnel is bereikbaar op zijn url zodra de client van het apparaat is verbonden. Stop hem weer met /actions/stop.
Eindpuntgroepen #
Alle onderstaande paden zijn relatief ten opzichte van https://localtonet.com/api/v2.
Tunnels #
| Methode | Pad | Doel |
|---|---|---|
| GET | /tunnels | Geef al je tunnels weer. |
| GET | /tunnels/{tunnelId} | Haal één tunnel op. |
| POST | /tunnels/http/random-subdomain | Maak een HTTP-, File Server- of MCP Gateway-tunnel aan met een willekeurig subdomein. |
| POST | /tunnels/http/custom-subdomain | Maak er een aan met een subdomein dat je zelf kiest. |
| POST | /tunnels/http/custom-domain | Maak er een aan op je eigen domein. |
| POST | /tunnels/tcp-udp | Maak een TCP-, UDP- of gecombineerde TCP- en UDP-tunnel aan. |
| POST | /tunnels/proxy | Maak een HTTP-, SOCKS5-, Shadowsocks- of VLESS-proxytunnel aan. |
| POST | /tunnels/proxy/with-detail | Maak een proxytunnel aan en geef de volledige verbindingsgegevens terug. |
| POST | /tunnels/shared-proxy | Maak een gedeelde (roterende) proxytunnel aan. |
| POST | /tunnels/{tunnelId}/actions/start | Start een tunnel. |
| POST | /tunnels/{tunnelId}/actions/stop | Stop een tunnel. |
| DELETE | /tunnels/{tunnelId} | Verwijder een tunnel definitief. |
| PATCH | /tunnels/{tunnelId}/title | Wijzig de titel. |
| PATCH | /tunnels/{tunnelId}/local-ip | Wijzig het lokale IP-adres. |
| PATCH | /tunnels/{tunnelId}/local-port | Wijzig de lokale poort. |
| PATCH | /tunnels/{tunnelId}/port-reserved | Zet poortreservering van een TCP/UDP-tunnel aan of uit. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | Zet de legacy-verbindingsmodus aan of uit. |
| PATCH | /tunnels/{tunnelId}/protocol-type | Wijzig het proxyprotocol van een proxytunnel. |
| GET | /tunnels/{tunnelId}/request-logs | Recente HTTP-requestlogboeken van een HTTP- of File Server-tunnel. |
Bulkbewerkingen voor tunnels #
| Methode | Pad | Doel |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | Maak meerdere HTTP-tunnels aan met willekeurige subdomeinen. |
| POST | /tunnels/bulk/http/custom-subdomain | Maak er meerdere aan met eigen subdomeinen. |
| POST | /tunnels/bulk/http/custom-domain | Maak er meerdere aan op eigen domeinen. |
| POST | /tunnels/bulk/tcp-udp | Maak meerdere TCP/UDP-tunnels aan. |
| POST | /tunnels/bulk/proxy | Maak meerdere proxytunnels aan. |
| POST | /tunnels/bulk/proxy/with-detail | Maak meerdere proxytunnels aan en geef hun verbindingsgegevens terug. |
| POST | /tunnels/bulk/shared-proxy | Maak meerdere gedeelde (roterende) proxytunnels aan. |
| POST | /tunnels/bulk/actions/start | Start meerdere tunnels. Body: een array van tunnel-ID's, bijvoorbeeld [123, 456]. |
| POST | /tunnels/bulk/actions/stop | Stop meerdere tunnels. Body: een array van tunnel-ID's. |
| DELETE | /tunnels/bulk | Verwijder meerdere tunnels. Body: een array van tunnel-ID's. |
| PATCH | /tunnels/bulk/protocol-type | Wijzig het proxyprotocol van meerdere proxytunnels. |
Tunnelconfiguratie #
Met deze eindpunten wijzig je de instellingen van één tunnel. Ze beginnen allemaal met /tunnels/{tunnelId}. Wat elke instelling doet, staat in de Instellingenreferentie.
| Methoden | Pad na /tunnels/{tunnelId} | Doel |
|---|---|---|
| GET, POST, PATCH, DELETE | /ip-restrictions | Geef IP-beperkingen weer, voeg ze toe, stel de toestaan- of weigermodus in, of verwijder ze allemaal. Verwijder er één met /ip-restrictions/{restrictionId}. |
| GET, POST, PATCH, DELETE | /access-controls | Hetzelfde voor toegangsregels op URL-paden. Verwijder er één met /access-controls/{controlId}. |
| GET, PATCH | /headers | Aangepaste HTTP-headers. |
| GET, PATCH | /authentication | HTTP Basic-authenticatie. |
| GET, PATCH | /expiration | Vervaldatum van de tunnel. |
| GET, PATCH | /server-port | Serverpoort van een TCP/UDP-tunnel. |
| GET, PATCH | /http-timeout | Time-out van HTTP-verzoeken. |
| GET, PATCH | /rate-limit | Snelheidslimiet. |
| GET, PATCH | /bandwidth-limit | Limiet voor de totale gegevensoverdracht. |
| GET | /bandwidth-usage | Huidig bandbreedtegebruik. Zet de teller terug met POST /bandwidth-usage/reset. |
| GET, PATCH | /arguments | Aangepaste opdrachtregelargumenten voor de tunnel. |
| GET, POST | /shared-proxy-clients | Geef clients van een gedeelde (roterende) proxytunnel weer of voeg ze toe. Werk er één bij of verwijder hem met PATCH of DELETE /shared-proxy-clients/{clientId}. |
| GET | /advanced-settings | Alle geavanceerde instellingen van de tunnel in één antwoord. |
| GET, PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | Lees één geavanceerde instelling of schakel hem om. |
| PATCH | /ssl-stream | Schakel de SSL-streaminstelling om. |
| GET, PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | Lees of wijzig één waarde. |
| GET, PUT | /token-groups | De tokengroepen die aan de tunnel zijn toegewezen. |
| GET, PATCH | /server | De server van de tunnel. |
AuthTokens #
| Methode | Pad | Doel |
|---|---|---|
| GET | /auth-tokens | Geef je AuthTokens weer. |
| GET | /auth-tokens/detail | Geef je AuthTokens met details weer. |
| GET | /auth-tokens/{token} | Details van één AuthToken. |
| POST | /auth-tokens | Maak een AuthToken aan. |
| DELETE | /auth-tokens/{token} | Verwijder een AuthToken. |
| GET | /auth-tokens/{token}/tunnels | De tunnels van een AuthToken. |
| GET | /auth-tokens/{token}/ip-history | Wijzigingsgeschiedenis van het openbare IP-adres van het apparaat. |
| GET, PATCH | /auth-tokens/{token}/airplane-mode-settings | Instellingen voor automatisering van de vliegtuigmodus. |
| POST | /auth-tokens/{token}/change-ip-links/{airplaneModeSettingId} | Voeg een link voor IP wijzigen toe. |
| DELETE | /auth-tokens/{token}/change-ip-links/{id} | Verwijder een link voor IP wijzigen. |
| POST | /auth-tokens/{token}/restart-device-links/{airplaneModeSettingId} | Voeg een link voor het herstarten van het apparaat toe. |
| DELETE | /auth-tokens/{token}/restart-device-links/{id} | Verwijder een link voor het herstarten van het apparaat. |
| GET, PATCH | /auth-tokens/{token}/arguments | De clientargumenten die op de AuthToken zijn opgeslagen. |
Tokengroepen #
| Methode | Pad | Doel |
|---|---|---|
| GET | /token-groups | Geef je tokengroepen weer. |
| GET | /token-groups/{id} | Haal één tokengroep op. |
| POST | /token-groups | Maak een tokengroep aan. |
| DELETE | /token-groups/{id} | Verwijder een tokengroep. |
| POST | /token-groups/{id}/auth-tokens | Voeg een AuthToken aan de groep toe. |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | Verwijder een AuthToken uit de groep. |
Servers #
| Methode | Pad | Doel |
|---|---|---|
| GET | /servers | Geef de servers weer waarop je tunnels kunt aanmaken, met de serverCode die je in aanmaakverzoeken gebruikt. |
SSO-providers #
| Methode | Pad | Doel |
|---|---|---|
| GET | /sso-providers | Geef je SSO-providers weer. |
| GET | /sso-providers/default-endpoints | Standaardeindpunten voor een SSO-providertype. |
| POST | /sso-providers | Maak een SSO-provider aan of werk hem bij. |
| DELETE | /sso-providers/{id} | Verwijder een SSO-provider. |
| GET | /sso-providers/tunnel/{tunnelId} | De SSO-providers die voor een tunnel zijn geconfigureerd. Hier is tunnelId de GUID van de tunnel (guidId). |
| PUT | /sso-providers/tunnel/{tunnelId} | Sla de SSO-providers van een tunnel op. |
Zie Single sign-on voor wat de providers doen.
VPN-toegang #
VPN-toegang geeft een WireGuard- of OpenVPN-apparaatprofiel op een proxytunnel; al het verkeer van dat apparaat verlaat het netwerk via de proxy. Deze eindpunten beginnen met /tunnels/{tunnelId}/vpn-access.
| Methode | Pad na /tunnels/{tunnelId}/vpn-access | Doel |
|---|---|---|
| GET | (geen) | Geef de VPN-apparaten van de tunnel weer. |
| POST | (geen) | Maak een VPN-apparaat aan. |
| DELETE | /{peerId} | Verwijder (trek in) een VPN-apparaat. |
| POST | /{peerId}/regenerate | Genereer de sleutels van een VPN-apparaat opnieuw. |
| GET | /{peerId}/config | Download het configuratiebestand van een VPN-apparaat. |
| GET | /{peerId}/qr | QR-code van de configuratie van een WireGuard-apparaat. |
| GET | /{peerId}/credentials | Gebruikersnaam en wachtwoord van een OpenVPN-apparaat. |
Probleemoplossing #
Elk verzoek geeft 401 terug
Controleer de header: die moet Authorization: Bearer zijn, gevolgd door een spatie en de sleutel, zonder aanhalingstekens rond de sleutel. Als je Wijzigen in de kaart API-sleutel hebt geselecteerd, werkt de oude sleutel niet meer; kopieer de nieuwe.
Ik zie de AuthTokens van mijn team niet
Je gebruikt de API-sleutel van je eigen account. Schakel over naar het teamdashboard en kopieer de API-sleutel daar.
De tunnel is aangemaakt, maar zijn adres reageert niet
Een nieuwe tunnel is gestopt. Roep POST /tunnels/{tunnelId}/actions/start aan en controleer of de Localtonet-client van het apparaat draait met de AuthToken die je hebt gebruikt.
Ik krijg 429 Too Many Requests
Verzoeken zijn aan een limiet gebonden. Wacht, stuur het verzoek daarna opnieuw en vervang lussen van losse aanroepen door één bulkverzoek.