Naar de inhoud
Localtonet Localtonet Dashboard

Localtonet REST API

Hulp bij deze pagina
Op deze pagina 8 secties
  1. Interactieve referentie
  2. Voordat je begint
  3. Basis-URL en authenticatie
  4. Conventies
  5. Fouten
  6. Limieten
  7. Voorbeelden
  8. Je tunnels weergeven
  9. Een HTTP-tunnel met een willekeurig subdomein aanmaken
  10. Start de tunnel
  11. Eindpuntgroepen
  12. Tunnels
  13. Bulkbewerkingen voor tunnels
  14. Tunnelconfiguratie
  15. AuthTokens
  16. Tokengroepen
  17. Servers
  18. SSO-providers
  19. VPN-toegang
  20. Probleemoplossing
  21. 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:

Basis-URL
https://localtonet.com/api/v2

Stuur de API-sleutel als Bearer-token mee in de Authorization-header van elk verzoek:

HTTP
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 #

OnderwerpHoe de API zich gedraagt
FormaatRequest- en responsebodies zijn JSON. Stuur Content-Type: application/json mee met een body.
Tunnel-IDDe 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.
Succescodes200 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-eindpuntenPaden die /bulk/ bevatten, nemen een JSON-array aan en accepteren maximaal 100 items per verzoek (/tunnels/bulk/protocol-type: maximaal 500).
Nieuwe tunnelsEen 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 #

StatusBetekenisBody
400De 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.
401De API-sleutel ontbreekt of is ongeldig.Geen specifiek bericht
403, 409Wordt 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.
404De tunnel of het object is niet gevonden of is niet van jou.Leeg of een probleemobject
429Te 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 #

Bash
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:

Bash
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:

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
  }'
VeldBetekenisWaarden
authTokenDe AuthToken van het apparaat dat de tunnel draait.Vereist
serverCodeDe server, uit GET /servers.Vereist
protocolTypeHet tunneltype.1 HTTP, 5 File Server, 24 MCP Gateway
ipHet lokale IP-adres waarnaar de tunnel doorstuurt.Een geldig IP-adres, bijvoorbeeld 127.0.0.1
portDe lokale poort.1 tot 65534
pathDe 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 #

Bash
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 #

MethodePadDoel
GET/tunnelsGeef al je tunnels weer.
GET/tunnels/{tunnelId}Haal één tunnel op.
POST/tunnels/http/random-subdomainMaak een HTTP-, File Server- of MCP Gateway-tunnel aan met een willekeurig subdomein.
POST/tunnels/http/custom-subdomainMaak er een aan met een subdomein dat je zelf kiest.
POST/tunnels/http/custom-domainMaak er een aan op je eigen domein.
POST/tunnels/tcp-udpMaak een TCP-, UDP- of gecombineerde TCP- en UDP-tunnel aan.
POST/tunnels/proxyMaak een HTTP-, SOCKS5-, Shadowsocks- of VLESS-proxytunnel aan.
POST/tunnels/proxy/with-detailMaak een proxytunnel aan en geef de volledige verbindingsgegevens terug.
POST/tunnels/shared-proxyMaak een gedeelde (roterende) proxytunnel aan.
POST/tunnels/{tunnelId}/actions/startStart een tunnel.
POST/tunnels/{tunnelId}/actions/stopStop een tunnel.
DELETE/tunnels/{tunnelId}Verwijder een tunnel definitief.
PATCH/tunnels/{tunnelId}/titleWijzig de titel.
PATCH/tunnels/{tunnelId}/local-ipWijzig het lokale IP-adres.
PATCH/tunnels/{tunnelId}/local-portWijzig de lokale poort.
PATCH/tunnels/{tunnelId}/port-reservedZet poortreservering van een TCP/UDP-tunnel aan of uit.
PATCH/tunnels/{tunnelId}/legacy-connectZet de legacy-verbindingsmodus aan of uit.
PATCH/tunnels/{tunnelId}/protocol-typeWijzig het proxyprotocol van een proxytunnel.
GET/tunnels/{tunnelId}/request-logsRecente HTTP-requestlogboeken van een HTTP- of File Server-tunnel.

Bulkbewerkingen voor tunnels #

MethodePadDoel
POST/tunnels/bulk/http/random-subdomainMaak meerdere HTTP-tunnels aan met willekeurige subdomeinen.
POST/tunnels/bulk/http/custom-subdomainMaak er meerdere aan met eigen subdomeinen.
POST/tunnels/bulk/http/custom-domainMaak er meerdere aan op eigen domeinen.
POST/tunnels/bulk/tcp-udpMaak meerdere TCP/UDP-tunnels aan.
POST/tunnels/bulk/proxyMaak meerdere proxytunnels aan.
POST/tunnels/bulk/proxy/with-detailMaak meerdere proxytunnels aan en geef hun verbindingsgegevens terug.
POST/tunnels/bulk/shared-proxyMaak meerdere gedeelde (roterende) proxytunnels aan.
POST/tunnels/bulk/actions/startStart meerdere tunnels. Body: een array van tunnel-ID's, bijvoorbeeld [123, 456].
POST/tunnels/bulk/actions/stopStop meerdere tunnels. Body: een array van tunnel-ID's.
DELETE/tunnels/bulkVerwijder meerdere tunnels. Body: een array van tunnel-ID's.
PATCH/tunnels/bulk/protocol-typeWijzig 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.

MethodenPad na /tunnels/{tunnelId}Doel
GET, POST, PATCH, DELETE/ip-restrictionsGeef 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-controlsHetzelfde voor toegangsregels op URL-paden. Verwijder er één met /access-controls/{controlId}.
GET, PATCH/headersAangepaste HTTP-headers.
GET, PATCH/authenticationHTTP Basic-authenticatie.
GET, PATCH/expirationVervaldatum van de tunnel.
GET, PATCH/server-portServerpoort van een TCP/UDP-tunnel.
GET, PATCH/http-timeoutTime-out van HTTP-verzoeken.
GET, PATCH/rate-limitSnelheidslimiet.
GET, PATCH/bandwidth-limitLimiet voor de totale gegevensoverdracht.
GET/bandwidth-usageHuidig bandbreedtegebruik. Zet de teller terug met POST /bandwidth-usage/reset.
GET, PATCH/argumentsAangepaste opdrachtregelargumenten voor de tunnel.
GET, POST/shared-proxy-clientsGeef 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-settingsAlle geavanceerde instellingen van de tunnel in één antwoord.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3Lees één geavanceerde instelling of schakel hem om.
PATCH/ssl-streamSchakel de SSL-streaminstelling om.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessLees of wijzig één waarde.
GET, PUT/token-groupsDe tokengroepen die aan de tunnel zijn toegewezen.
GET, PATCH/serverDe server van de tunnel.

AuthTokens #

MethodePadDoel
GET/auth-tokensGeef je AuthTokens weer.
GET/auth-tokens/detailGeef je AuthTokens met details weer.
GET/auth-tokens/{token}Details van één AuthToken.
POST/auth-tokensMaak een AuthToken aan.
DELETE/auth-tokens/{token}Verwijder een AuthToken.
GET/auth-tokens/{token}/tunnelsDe tunnels van een AuthToken.
GET/auth-tokens/{token}/ip-historyWijzigingsgeschiedenis van het openbare IP-adres van het apparaat.
GET, PATCH/auth-tokens/{token}/airplane-mode-settingsInstellingen 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}/argumentsDe clientargumenten die op de AuthToken zijn opgeslagen.

Tokengroepen #

MethodePadDoel
GET/token-groupsGeef je tokengroepen weer.
GET/token-groups/{id}Haal één tokengroep op.
POST/token-groupsMaak een tokengroep aan.
DELETE/token-groups/{id}Verwijder een tokengroep.
POST/token-groups/{id}/auth-tokensVoeg een AuthToken aan de groep toe.
DELETE/token-groups/{id}/auth-tokens/{tokenId}Verwijder een AuthToken uit de groep.

Servers #

MethodePadDoel
GET/serversGeef de servers weer waarop je tunnels kunt aanmaken, met de serverCode die je in aanmaakverzoeken gebruikt.

SSO-providers #

MethodePadDoel
GET/sso-providersGeef je SSO-providers weer.
GET/sso-providers/default-endpointsStandaardeindpunten voor een SSO-providertype.
POST/sso-providersMaak 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.

MethodePad na /tunnels/{tunnelId}/vpn-accessDoel
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}/regenerateGenereer de sleutels van een VPN-apparaat opnieuw.
GET/{peerId}/configDownload het configuratiebestand van een VPN-apparaat.
GET/{peerId}/qrQR-code van de configuratie van een WireGuard-apparaat.
GET/{peerId}/credentialsGebruikersnaam 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.

Support