Localtonet-REST-API
Auf dieser Seite 8 Abschnitte
- Interaktive Referenz
- Bevor Sie beginnen
- Basis-URL und Authentifizierung
- Konventionen
- Fehler
- Ratenbegrenzung
- Beispiele
- Ihre Tunnel auflisten
- Einen HTTP-Tunnel mit zufälliger Subdomain erstellen
- Den Tunnel starten
- Endpunktgruppen
- Tunnel
- Bulk-Operationen für Tunnel
- Tunnelkonfiguration
- AuthTokens
- Token-Gruppen
- Server
- SSO-Anbieter
- VPN-Zugang
- Fehlerbehebung
- 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:
https://localtonet.com/api/v2Senden Sie den API-Schlüssel bei jeder Anfrage als Bearer-Token im Header Authorization:
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 #
| Thema | Wie sich die API verhält |
|---|---|
| Format | Anfrage- und Antwortinhalte sind JSON. Senden Sie bei einem Inhalt Content-Type: application/json mit. |
| Tunnel-ID | Die 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. |
| Erfolgscodes | 200 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-Endpunkte | Pfade, die /bulk/ enthalten, nehmen ein JSON-Array entgegen und akzeptieren bis zu 100 Elemente pro Anfrage (/tunnels/bulk/protocol-type: bis zu 500). |
| Neue Tunnel | Ein 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 #
| Status | Bedeutung | Inhalt |
|---|---|---|
400 | Der 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. |
401 | Der API-Schlüssel fehlt oder ist ungültig. | Keine spezifische Meldung |
403, 409 | Wird 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. |
404 | Der Tunnel oder das Objekt wurde nicht gefunden oder gehört Ihnen nicht. | Leer oder ein Problem-Objekt |
429 | Zu 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 #
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:
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:
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
}'| Feld | Bedeutung | Werte |
|---|---|---|
authToken | Der AuthToken des Geräts, auf dem der Tunnel läuft. | Erforderlich |
serverCode | Der Server, aus GET /servers. | Erforderlich |
protocolType | Der Tunneltyp. | 1 HTTP, 5 File Server, 24 MCP Gateway |
ip | Die lokale IP-Adresse, an die der Tunnel weiterleitet. | Eine gültige IP-Adresse, zum Beispiel 127.0.0.1 |
port | Der lokale Port. | 1 bis 65534 |
path | Der 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 #
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 #
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /tunnels | Alle Ihre Tunnel auflisten. |
| GET | /tunnels/{tunnelId} | Einen Tunnel abrufen. |
| POST | /tunnels/http/random-subdomain | Einen HTTP-, Dateiserver- oder MCP-Gateway-Tunnel mit zufälliger Subdomain erstellen. |
| POST | /tunnels/http/custom-subdomain | Einen mit einer von Ihnen gewählten Subdomain erstellen. |
| POST | /tunnels/http/custom-domain | Einen auf Ihrer eigenen Domain erstellen. |
| POST | /tunnels/tcp-udp | Einen TCP-, UDP- oder kombinierten TCP-und-UDP-Tunnel erstellen. |
| POST | /tunnels/proxy | Einen HTTP-, SOCKS5-, Shadowsocks- oder VLESS-Proxy-Tunnel erstellen. |
| POST | /tunnels/proxy/with-detail | Einen Proxy-Tunnel erstellen und seine vollständigen Verbindungsdetails zurückgeben. |
| POST | /tunnels/shared-proxy | Einen gemeinsamen (rotierenden) Proxy-Tunnel erstellen. |
| POST | /tunnels/{tunnelId}/actions/start | Einen Tunnel starten. |
| POST | /tunnels/{tunnelId}/actions/stop | Einen Tunnel stoppen. |
| DELETE | /tunnels/{tunnelId} | Einen Tunnel dauerhaft löschen. |
| PATCH | /tunnels/{tunnelId}/title | Den Titel ändern. |
| PATCH | /tunnels/{tunnelId}/local-ip | Die lokale IP-Adresse ändern. |
| PATCH | /tunnels/{tunnelId}/local-port | Den lokalen Port ändern. |
| PATCH | /tunnels/{tunnelId}/port-reserved | Die Portreservierung eines TCP/UDP-Tunnels ein- oder ausschalten. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | Den Legacy-Verbindungsmodus ein- oder ausschalten. |
| PATCH | /tunnels/{tunnelId}/protocol-type | Das Proxy-Protokoll eines Proxy-Tunnels ändern. |
| GET | /tunnels/{tunnelId}/request-logs | Aktuelle HTTP-Anfrageprotokolle eines HTTP- oder Dateiserver-Tunnels. |
Bulk-Operationen für Tunnel #
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | Mehrere HTTP-Tunnel mit zufälligen Subdomains erstellen. |
| POST | /tunnels/bulk/http/custom-subdomain | Mehrere mit benutzerdefinierten Subdomains erstellen. |
| POST | /tunnels/bulk/http/custom-domain | Mehrere auf eigenen Domains erstellen. |
| POST | /tunnels/bulk/tcp-udp | Mehrere TCP/UDP-Tunnel erstellen. |
| POST | /tunnels/bulk/proxy | Mehrere Proxy-Tunnel erstellen. |
| POST | /tunnels/bulk/proxy/with-detail | Mehrere Proxy-Tunnel erstellen und ihre Verbindungsdetails zurückgeben. |
| POST | /tunnels/bulk/shared-proxy | Mehrere gemeinsame (rotierende) Proxy-Tunnel erstellen. |
| POST | /tunnels/bulk/actions/start | Mehrere Tunnel starten. Inhalt: ein Array von Tunnel-IDs, zum Beispiel [123, 456]. |
| POST | /tunnels/bulk/actions/stop | Mehrere Tunnel stoppen. Inhalt: ein Array von Tunnel-IDs. |
| DELETE | /tunnels/bulk | Mehrere Tunnel löschen. Inhalt: ein Array von Tunnel-IDs. |
| PATCH | /tunnels/bulk/protocol-type | Das 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.
| Methoden | Pfad nach /tunnels/{tunnelId} | Zweck |
|---|---|---|
| GET, POST, PATCH, DELETE | /ip-restrictions | Alle 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-controls | Dasselbe für Zugriffskontrollen auf URL-Pfade. Eine einzelne löschen Sie mit /access-controls/{controlId}. |
| GET, PATCH | /headers | Benutzerdefinierte HTTP-Header. |
| GET, PATCH | /authentication | HTTP Basic Authentication. |
| GET, PATCH | /expiration | Ablaufdatum des Tunnels. |
| GET, PATCH | /server-port | Serverseitiger Port eines TCP/UDP-Tunnels. |
| GET, PATCH | /http-timeout | Zeitlimit für HTTP-Anfragen. |
| GET, PATCH | /rate-limit | Geschwindigkeitslimit. |
| GET, PATCH | /bandwidth-limit | Limit für die gesamte Datenübertragung. |
| GET | /bandwidth-usage | Aktuelle Bandbreitennutzung. Setzen Sie den Zähler mit POST /bandwidth-usage/reset zurück. |
| GET, PATCH | /arguments | Benutzerdefinierte Kommandozeilenargumente für den Tunnel. |
| GET, POST | /shared-proxy-clients | Clients 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-settings | Alle erweiterten Einstellungen des Tunnels in einer Antwort. |
| GET, PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | Eine erweiterte Einstellung lesen oder umschalten. |
| PATCH | /ssl-stream | Die Einstellung SSL-Stream umschalten. |
| GET, PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | Einen Wert lesen oder ändern. |
| GET, PUT | /token-groups | Die dem Tunnel zugewiesenen Token-Gruppen. |
| GET, PATCH | /server | Der Server des Tunnels. |
AuthTokens #
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /auth-tokens | Ihre AuthTokens auflisten. |
| GET | /auth-tokens/detail | Ihre AuthTokens mit Details auflisten. |
| GET | /auth-tokens/{token} | Details eines AuthTokens. |
| POST | /auth-tokens | Einen AuthToken erstellen. |
| DELETE | /auth-tokens/{token} | Einen AuthToken löschen. |
| GET | /auth-tokens/{token}/tunnels | Die Tunnel eines AuthTokens. |
| GET | /auth-tokens/{token}/ip-history | Verlauf der Änderungen der öffentlichen IP-Adresse des Geräts. |
| GET, PATCH | /auth-tokens/{token}/airplane-mode-settings | Einstellungen 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}/arguments | Die im AuthToken gespeicherten Client-Argumente. |
Token-Gruppen #
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /token-groups | Ihre Token-Gruppen auflisten. |
| GET | /token-groups/{id} | Eine Token-Gruppe abrufen. |
| POST | /token-groups | Eine Token-Gruppe erstellen. |
| DELETE | /token-groups/{id} | Eine Token-Gruppe löschen. |
| POST | /token-groups/{id}/auth-tokens | Einen AuthToken zur Gruppe hinzufügen. |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | Einen AuthToken aus der Gruppe entfernen. |
Server #
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /servers | Die Server auflisten, auf denen Sie Tunnel erstellen können, mit dem serverCode, der in Erstellungsanfragen zu verwenden ist. |
SSO-Anbieter #
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /sso-providers | Ihre SSO-Anbieter auflisten. |
| GET | /sso-providers/default-endpoints | Standard-Endpunkte für einen SSO-Anbietertyp. |
| POST | /sso-providers | Einen 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.
| Methode | Pfad nach /tunnels/{tunnelId}/vpn-access | Zweck |
|---|---|---|
| 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}/regenerate | Die Schlüssel eines VPN-Geräts neu erzeugen. |
| GET | /{peerId}/config | Die Konfigurationsdatei eines VPN-Geräts herunterladen. |
| GET | /{peerId}/qr | QR-Code der Konfiguration eines WireGuard-Geräts. |
| GET | /{peerId}/credentials | Benutzername 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.