Zum Inhalt springen
Localtonet Localtonet Dashboard

Localtonet-REST-API

Hilfe zu dieser Seite
Auf dieser Seite 8 Abschnitte
  1. Interaktive Referenz
  2. Bevor Sie beginnen
  3. Basis-URL und Authentifizierung
  4. Konventionen
  5. Fehler
  6. Ratenbegrenzung
  7. Beispiele
  8. Ihre Tunnel auflisten
  9. Einen HTTP-Tunnel mit zufälliger Subdomain erstellen
  10. Den Tunnel starten
  11. Endpunktgruppen
  12. Tunnel
  13. Bulk-Operationen für Tunnel
  14. Tunnelkonfiguration
  15. AuthTokens
  16. Token-Gruppen
  17. Server
  18. SSO-Anbieter
  19. VPN-Zugang
  20. Fehlerbehebung
  21. Verwandte Seiten

Die REST-API v2 leistet für Tunnel dasselbe wie das Dashboard: Sie erstellen, starten, stoppen, löschen und konfigurieren sie und verwalten AuthTokens, Token-Gruppen und SSO-Anbieter. Jede Anfrage authentifizieren Sie mit Ihrem API-Schlüssel.

Interaktive Referenz #

Jeder Endpunkt mit seinen Anfrage- und Antwortmodellen und einem Formular zum Ausprobieren steht in der interaktiven Referenz:

  • localtonet.com/api: API v2, die aktuelle Version. Sie erreichen sie auch über die Schaltfläche API-Oberfläche im Dashboard.
  • localtonet.com/api/v1: API v1, für bestehende Integrationen beibehalten. Nutzen Sie für neue Projekte v2.

Diese Seite beschreibt die Konventionen und gibt einen Überblick über die Endpunktgruppen. Die genauen Felder einer Anfrage finden Sie, wenn Sie den Endpunkt in der Referenz öffnen.

Bevor Sie beginnen #

  • Ihr API-Schlüssel. Öffnen Sie das Dashboard und wählen Sie in der Karte API-Schlüssel die Option Kopieren. Siehe Konto und Sicherheit.
  • Zum Erstellen eines Tunnels: ein AuthToken des Geräts, auf dem der Tunnel laufen wird, und ein mit diesem Token verbundener Localtonet-Client. Siehe AuthTokens.

Halten Sie Ihren API-Schlüssel geheim. Wer ihn besitzt, kann Ihre Tunnel und Tokens erstellen, ändern und löschen. Ändern in der Karte API-Schlüssel erstellt einen neuen Schlüssel und macht den alten ungültig.

Basis-URL und Authentifizierung #

Alle v2-Endpunkte beginnen mit:

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

Senden Sie den API-Schlüssel bei jeder Anfrage als Bearer-Token im Header Authorization:

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

Ein API-Schlüssel, der in einem Team-Dashboard kopiert wurde, listet Ihre AuthTokens und Tunnel in diesem Team auf; der Schlüssel Ihres eigenen Kontos listet die AuthTokens auf, die zu keinem Team gehören.

Konventionen #

ThemaWie sich die API verhält
FormatAnfrage- und Antwortinhalte sind JSON. Senden Sie bei einem Inhalt Content-Type: application/json mit.
Tunnel-IDDie tunnelId in einem Pfad ist die numerische id des Tunnels, wie sie von den Listen- und Erstellungs-Endpunkten zurückgegeben wird.
AuthToken in einem Pfad{token} ist der AuthToken-String selbst.
Erfolgscodes200 mit Inhalt bei Lesezugriffen, 201 bei den meisten Erstellungen (die Endpunkte zum Erstellen von Tunneln geben den neuen Tunnel zurück), 204 ohne Inhalt bei den meisten Aktionen und Aktualisierungen. Die Referenz zeigt die Antwort jedes Endpunkts.
Bulk-EndpunktePfade, die /bulk/ enthalten, nehmen ein JSON-Array entgegen und akzeptieren bis zu 100 Elemente pro Anfrage (/tunnels/bulk/protocol-type: bis zu 500).
Neue TunnelEin von Ihnen erstellter Tunnel läuft noch nicht. Starten Sie ihn mit der Start-Aktion. Nur die Endpunkte proxy/with-detail können den Tunnel mit isStartAfterCreate im selben Aufruf starten.

Fehler #

StatusBedeutungInhalt
400Der Anfrageinhalt ist ungültig, oder der Vorgang wurde abgelehnt, zum Beispiel wegen eines Limits Ihres Plans.Bei den meisten Endpunkten ein Problem-Objekt in JSON; title enthält die Meldung. Validierungsfehler und die Fehler von Bulk-Endpunkten stehen unter errors.
401Der API-Schlüssel fehlt oder ist ungültig.Keine spezifische Meldung
403, 409Wird von einigen Endpunkten für die Tunnelkonfiguration und den VPN-Zugang zurückgegeben, wenn die Änderung nicht zulässig ist oder mit der aktuellen Konfiguration in Konflikt steht.Ein Problem-Objekt mit der Meldung in title.
404Der Tunnel oder das Objekt wurde nicht gefunden oder gehört Ihnen nicht.Leer oder ein Problem-Objekt
429Zu viele Anfragen.Siehe die Ratenbegrenzung weiter unten.

Ratenbegrenzung #

Anfragen unterliegen einer Ratenbegrenzung. Eine Anfrage über dem Limit wird mit 429 Too Many Requests beantwortet. Warten Sie und senden Sie sie erneut; verwenden Sie die Bulk-Endpunkte statt vieler Einzelaufrufe.

Beispiele #

Ersetzen Sie <YOUR_API_KEY> durch Ihren API-Schlüssel und <YOUR_TOKEN> durch den AuthToken des Geräts.

Ihre Tunnel auflisten #

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

Die Antwort ist ein JSON-Array mit einem Objekt pro Tunnel. Zu seinen Feldern gehören id, title, url (die öffentliche Adresse), protocolType, authToken, serverId, clientIp und clientPort (das lokale Ziel), status und connectionStatus. Wenn Sie noch keine Tunnel haben, lautet die Antwort 404 statt eines leeren Arrays.

Einen HTTP-Tunnel mit zufälliger Subdomain erstellen #

Ermitteln Sie zuerst den Code des Servers, den Sie verwenden möchten:

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

Jeder Eintrag hat einen serverCode, einen serverName und eine serverDomain. Erstellen Sie dann den Tunnel. Dieses Beispiel leitet an eine Web-App auf Port 3000 des Geräts weiter:

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
  }'
FeldBedeutungWerte
authTokenDer AuthToken des Geräts, auf dem der Tunnel läuft.Erforderlich
serverCodeDer Server, aus GET /servers.Erforderlich
protocolTypeDer Tunneltyp.1 HTTP, 5 File Server, 24 MCP Gateway
ipDie lokale IP-Adresse, an die der Tunnel weiterleitet.Eine gültige IP-Adresse, zum Beispiel 127.0.0.1
portDer lokale Port.1 bis 65534
pathDer lokale Ordner, der freigegeben wird.Nur für Dateiserver erforderlich

Die Antwort ist 201 Created mit dem neuen Tunnel. Notieren Sie sich dessen id und url.

Den Tunnel starten #

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

Die Antwort ist 204 No Content. Der Tunnel ist unter seiner url erreichbar, sobald der Client des Geräts verbunden ist. Stoppen Sie ihn wieder mit /actions/stop.

Endpunktgruppen #

Alle folgenden Pfade sind relativ zu https://localtonet.com/api/v2.

Tunnel #

MethodePfadZweck
GET/tunnelsAlle Ihre Tunnel auflisten.
GET/tunnels/{tunnelId}Einen Tunnel abrufen.
POST/tunnels/http/random-subdomainEinen HTTP-, Dateiserver- oder MCP-Gateway-Tunnel mit zufälliger Subdomain erstellen.
POST/tunnels/http/custom-subdomainEinen mit einer von Ihnen gewählten Subdomain erstellen.
POST/tunnels/http/custom-domainEinen auf Ihrer eigenen Domain erstellen.
POST/tunnels/tcp-udpEinen TCP-, UDP- oder kombinierten TCP-und-UDP-Tunnel erstellen.
POST/tunnels/proxyEinen HTTP-, SOCKS5-, Shadowsocks- oder VLESS-Proxy-Tunnel erstellen.
POST/tunnels/proxy/with-detailEinen Proxy-Tunnel erstellen und seine vollständigen Verbindungsdetails zurückgeben.
POST/tunnels/shared-proxyEinen gemeinsamen (rotierenden) Proxy-Tunnel erstellen.
POST/tunnels/{tunnelId}/actions/startEinen Tunnel starten.
POST/tunnels/{tunnelId}/actions/stopEinen Tunnel stoppen.
DELETE/tunnels/{tunnelId}Einen Tunnel dauerhaft löschen.
PATCH/tunnels/{tunnelId}/titleDen Titel ändern.
PATCH/tunnels/{tunnelId}/local-ipDie lokale IP-Adresse ändern.
PATCH/tunnels/{tunnelId}/local-portDen lokalen Port ändern.
PATCH/tunnels/{tunnelId}/port-reservedDie Portreservierung eines TCP/UDP-Tunnels ein- oder ausschalten.
PATCH/tunnels/{tunnelId}/legacy-connectDen Legacy-Verbindungsmodus ein- oder ausschalten.
PATCH/tunnels/{tunnelId}/protocol-typeDas Proxy-Protokoll eines Proxy-Tunnels ändern.
GET/tunnels/{tunnelId}/request-logsAktuelle HTTP-Anfrageprotokolle eines HTTP- oder Dateiserver-Tunnels.

Bulk-Operationen für Tunnel #

MethodePfadZweck
POST/tunnels/bulk/http/random-subdomainMehrere HTTP-Tunnel mit zufälligen Subdomains erstellen.
POST/tunnels/bulk/http/custom-subdomainMehrere mit benutzerdefinierten Subdomains erstellen.
POST/tunnels/bulk/http/custom-domainMehrere auf eigenen Domains erstellen.
POST/tunnels/bulk/tcp-udpMehrere TCP/UDP-Tunnel erstellen.
POST/tunnels/bulk/proxyMehrere Proxy-Tunnel erstellen.
POST/tunnels/bulk/proxy/with-detailMehrere Proxy-Tunnel erstellen und ihre Verbindungsdetails zurückgeben.
POST/tunnels/bulk/shared-proxyMehrere gemeinsame (rotierende) Proxy-Tunnel erstellen.
POST/tunnels/bulk/actions/startMehrere Tunnel starten. Inhalt: ein Array von Tunnel-IDs, zum Beispiel [123, 456].
POST/tunnels/bulk/actions/stopMehrere Tunnel stoppen. Inhalt: ein Array von Tunnel-IDs.
DELETE/tunnels/bulkMehrere Tunnel löschen. Inhalt: ein Array von Tunnel-IDs.
PATCH/tunnels/bulk/protocol-typeDas Proxy-Protokoll mehrerer Proxy-Tunnel ändern.

Tunnelkonfiguration #

Diese Endpunkte ändern die Einstellungen eines einzelnen Tunnels. Sie beginnen alle mit /tunnels/{tunnelId}. Was jede Einstellung bewirkt, beschreibt die Einstellungsreferenz.

MethodenPfad nach /tunnels/{tunnelId}Zweck
GET, POST, PATCH, DELETE/ip-restrictionsAlle IP-Beschränkungen auflisten, hinzufügen, den Zulassen- oder Verweigern-Modus setzen oder alle löschen. Eine einzelne löschen Sie mit /ip-restrictions/{restrictionId}.
GET, POST, PATCH, DELETE/access-controlsDasselbe für Zugriffskontrollen auf URL-Pfade. Eine einzelne löschen Sie mit /access-controls/{controlId}.
GET, PATCH/headersBenutzerdefinierte HTTP-Header.
GET, PATCH/authenticationHTTP Basic Authentication.
GET, PATCH/expirationAblaufdatum des Tunnels.
GET, PATCH/server-portServerseitiger Port eines TCP/UDP-Tunnels.
GET, PATCH/http-timeoutZeitlimit für HTTP-Anfragen.
GET, PATCH/rate-limitGeschwindigkeitslimit.
GET, PATCH/bandwidth-limitLimit für die gesamte Datenübertragung.
GET/bandwidth-usageAktuelle Bandbreitennutzung. Setzen Sie den Zähler mit POST /bandwidth-usage/reset zurück.
GET, PATCH/argumentsBenutzerdefinierte Kommandozeilenargumente für den Tunnel.
GET, POST/shared-proxy-clientsClients eines gemeinsamen (rotierenden) Proxy-Tunnels auflisten oder hinzufügen. Aktualisieren oder löschen Sie einen mit PATCH oder DELETE /shared-proxy-clients/{clientId}.
GET/advanced-settingsAlle erweiterten Einstellungen des Tunnels in einer Antwort.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3Eine erweiterte Einstellung lesen oder umschalten.
PATCH/ssl-streamDie Einstellung SSL-Stream umschalten.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessEinen Wert lesen oder ändern.
GET, PUT/token-groupsDie dem Tunnel zugewiesenen Token-Gruppen.
GET, PATCH/serverDer Server des Tunnels.

AuthTokens #

MethodePfadZweck
GET/auth-tokensIhre AuthTokens auflisten.
GET/auth-tokens/detailIhre AuthTokens mit Details auflisten.
GET/auth-tokens/{token}Details eines AuthTokens.
POST/auth-tokensEinen AuthToken erstellen.
DELETE/auth-tokens/{token}Einen AuthToken löschen.
GET/auth-tokens/{token}/tunnelsDie Tunnel eines AuthTokens.
GET/auth-tokens/{token}/ip-historyVerlauf der Änderungen der öffentlichen IP-Adresse des Geräts.
GET, PATCH/auth-tokens/{token}/airplane-mode-settingsEinstellungen der Flugmodus-Automatisierung.
POST/auth-tokens/{token}/change-ip-links/{airplaneModeSettingId}Einen Link zum Ändern der IP hinzufügen.
DELETE/auth-tokens/{token}/change-ip-links/{id}Einen Link zum Ändern der IP löschen.
POST/auth-tokens/{token}/restart-device-links/{airplaneModeSettingId}Einen Link zum Neustarten des Geräts hinzufügen.
DELETE/auth-tokens/{token}/restart-device-links/{id}Einen Link zum Neustarten des Geräts löschen.
GET, PATCH/auth-tokens/{token}/argumentsDie im AuthToken gespeicherten Client-Argumente.

Token-Gruppen #

MethodePfadZweck
GET/token-groupsIhre Token-Gruppen auflisten.
GET/token-groups/{id}Eine Token-Gruppe abrufen.
POST/token-groupsEine Token-Gruppe erstellen.
DELETE/token-groups/{id}Eine Token-Gruppe löschen.
POST/token-groups/{id}/auth-tokensEinen AuthToken zur Gruppe hinzufügen.
DELETE/token-groups/{id}/auth-tokens/{tokenId}Einen AuthToken aus der Gruppe entfernen.

Server #

MethodePfadZweck
GET/serversDie Server auflisten, auf denen Sie Tunnel erstellen können, mit dem serverCode, der in Erstellungsanfragen zu verwenden ist.

SSO-Anbieter #

MethodePfadZweck
GET/sso-providersIhre SSO-Anbieter auflisten.
GET/sso-providers/default-endpointsStandard-Endpunkte für einen SSO-Anbietertyp.
POST/sso-providersEinen SSO-Anbieter erstellen oder aktualisieren.
DELETE/sso-providers/{id}Einen SSO-Anbieter löschen.
GET/sso-providers/tunnel/{tunnelId}Die für einen Tunnel konfigurierten SSO-Anbieter. Hier ist tunnelId die GUID des Tunnels (guidId).
PUT/sso-providers/tunnel/{tunnelId}Die SSO-Anbieter eines Tunnels speichern.

Was die Anbieter leisten, lesen Sie unter Single Sign-On.

VPN-Zugang #

Der VPN-Zugang stellt auf einem Proxy-Tunnel ein WireGuard- oder OpenVPN-Geräteprofil bereit; der gesamte Datenverkehr dieses Geräts verlässt das Netz über den Proxy. Diese Endpunkte beginnen mit /tunnels/{tunnelId}/vpn-access.

MethodePfad nach /tunnels/{tunnelId}/vpn-accessZweck
GET(keiner)Die VPN-Geräte des Tunnels auflisten.
POST(keiner)Ein VPN-Gerät erstellen.
DELETE/{peerId}Ein VPN-Gerät löschen (widerrufen).
POST/{peerId}/regenerateDie Schlüssel eines VPN-Geräts neu erzeugen.
GET/{peerId}/configDie Konfigurationsdatei eines VPN-Geräts herunterladen.
GET/{peerId}/qrQR-Code der Konfiguration eines WireGuard-Geräts.
GET/{peerId}/credentialsBenutzername und Passwort eines OpenVPN-Geräts.

Fehlerbehebung #

Jede Anfrage liefert 401

Prüfen Sie den Header: Er muss Authorization: Bearer lauten, gefolgt von einem Leerzeichen und dem Schlüssel, ohne Anführungszeichen um den Schlüssel. Wenn Sie in der Karte API-Schlüssel Ändern gewählt haben, funktioniert der alte Schlüssel nicht mehr; kopieren Sie den neuen.

Ich sehe die AuthTokens meines Teams nicht

Sie verwenden den API-Schlüssel Ihres eigenen Kontos. Wechseln Sie zum Team-Dashboard und kopieren Sie dort den API-Schlüssel.

Der Tunnel wurde erstellt, aber seine Adresse antwortet nicht

Ein neuer Tunnel ist gestoppt. Rufen Sie POST /tunnels/{tunnelId}/actions/start auf und prüfen Sie, ob der Localtonet-Client des Geräts mit dem von Ihnen verwendeten AuthToken läuft.

Ich erhalte 429 Too Many Requests

Anfragen unterliegen einer Ratenbegrenzung. Warten Sie, senden Sie die Anfrage dann erneut und ersetzen Sie Schleifen aus Einzelaufrufen durch eine Bulk-Anfrage.

Brauchen Sie Hilfe zu dieser Seite? Fragen Sie die Community oder eröffnen Sie ein Support-Ticket.

Support