API REST di Localtonet
In questa pagina 8 sezioni
- Riferimento interattivo
- Prima di iniziare
- URL di base e autenticazione
- Convenzioni
- Errori
- Limiti di frequenza
- Esempi
- Elenca i tuoi tunnel
- Crea un tunnel HTTP con un sottodominio casuale
- Avvia il tunnel
- Gruppi di endpoint
- Tunnel
- Operazioni bulk sui tunnel
- Configurazione del tunnel
- AuthToken
- Gruppi di token
- Server
- Provider SSO
- Accesso VPN
- Risoluzione dei problemi
- Pagine correlate
L'API REST v2 fa ciò che fa la dashboard per i tunnel: creare, avviare, arrestare, eliminare e configurare i tunnel, oltre a gestire AuthToken, gruppi di token e provider SSO. Autentichi ogni richiesta con la tua chiave API.
Riferimento interattivo #
Ogni endpoint, con i relativi modelli di richiesta e risposta e un modulo per provarlo, si trova nel riferimento interattivo:
- localtonet.com/api: API v2, la versione attuale. La raggiungi anche con il pulsante Interfaccia API nella dashboard.
- localtonet.com/api/v1: API v1, mantenuta per le integrazioni esistenti. Per i nuovi lavori usa la v2.
Questa pagina ti presenta le convenzioni e una panoramica dei gruppi di endpoint. Per i campi esatti di una richiesta, apri l'endpoint nel riferimento.
Prima di iniziare #
- La tua chiave API. Apri la Dashboard e usa Copia nella scheda Chiave API. Consulta Account e sicurezza.
- Per creare un tunnel: un AuthToken del dispositivo che eseguirà il tunnel e un client Localtonet connesso con quel token. Consulta AuthToken.
Mantieni privata la tua chiave API. Chiunque la possieda può creare, modificare ed eliminare i tuoi tunnel e token. Cambia nella scheda Chiave API crea una nuova chiave e invalida quella vecchia.
URL di base e autenticazione #
Tutti gli endpoint v2 iniziano con:
https://localtonet.com/api/v2Invia la chiave API come token Bearer nell'intestazione Authorization di ogni richiesta:
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>Una chiave API copiata in una dashboard del team elenca gli AuthToken e i tunnel di quel team; la chiave del tuo account personale elenca gli AuthToken che non appartengono ad alcun team.
Convenzioni #
| Argomento | Come si comporta l'API |
|---|---|
| Formato | I corpi delle richieste e delle risposte sono in JSON. Invia Content-Type: application/json insieme al corpo. |
| ID del tunnel | Il tunnelId in un percorso è l'id numerico del tunnel, come restituito dagli endpoint di elenco e di creazione. |
| AuthToken in un percorso | {token} è la stringa dell'AuthToken stessa. |
| Codici di successo | 200 con un corpo per le letture, 201 per la maggior parte delle creazioni (gli endpoint di creazione dei tunnel restituiscono il nuovo tunnel), 204 senza corpo per la maggior parte delle azioni e degli aggiornamenti. Il riferimento mostra la risposta di ogni endpoint. |
| Endpoint bulk | I percorsi che contengono /bulk/ accettano un array JSON e fino a 100 elementi per richiesta (/tunnels/bulk/protocol-type: fino a 500). |
| Nuovi tunnel | Un tunnel che crei non è ancora in esecuzione. Avvialo con l'azione di avvio. Solo gli endpoint proxy/with-detail possono avviare il tunnel nella stessa chiamata, con isStartAfterCreate. |
Errori #
| Stato | Significato | Corpo |
|---|---|---|
400 | Il corpo della richiesta non è valido oppure l'operazione è stata rifiutata, per esempio a causa di un limite del tuo piano. | Per la maggior parte degli endpoint un oggetto problem in JSON; title contiene il messaggio. Gli errori di validazione e quelli degli endpoint bulk sono elencati in errors. |
401 | La chiave API è mancante o non valida. | Nessun messaggio specifico |
403, 409 | Restituito da alcuni endpoint di configurazione dei tunnel e di accesso VPN quando la modifica non è consentita o è in conflitto con la configurazione attuale. | Un oggetto problem con il messaggio in title. |
404 | Il tunnel o l'oggetto non è stato trovato oppure non ti appartiene. | Vuoto oppure un oggetto problem |
429 | Troppe richieste. | Vedi i limiti di frequenza qui sotto. |
Limiti di frequenza #
Le richieste hanno un limite di frequenza. Una richiesta oltre il limite riceve la risposta 429 Too Many Requests. Attendi e inviala di nuovo; usa gli endpoint bulk invece di molte chiamate singole.
Esempi #
Sostituisci <YOUR_API_KEY> con la tua chiave API e <YOUR_TOKEN> con l'AuthToken del dispositivo.
Elenca i tuoi tunnel #
curl https://localtonet.com/api/v2/tunnels \
-H "Authorization: Bearer <YOUR_API_KEY>"La risposta è un array JSON con un oggetto per ogni tunnel. Tra i suoi campi ci sono id, title, url (l'indirizzo pubblico), protocolType, authToken, serverId, clientIp e clientPort (la destinazione locale), status e connectionStatus. Se non hai ancora tunnel, la risposta è 404 invece di un array vuoto.
Crea un tunnel HTTP con un sottodominio casuale #
Prima ottieni il codice del server che vuoi usare:
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"Ogni voce ha un serverCode, un serverName e un serverDomain. Poi crea il tunnel. Questo esempio inoltra il traffico a un'app web sulla porta 3000 del dispositivo:
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
}'| Campo | Significato | Valori |
|---|---|---|
authToken | L'AuthToken del dispositivo che esegue il tunnel. | Obbligatorio |
serverCode | Il server, da GET /servers. | Obbligatorio |
protocolType | Il tipo di tunnel. | 1 HTTP, 5 File Server, 24 MCP Gateway |
ip | L'indirizzo IP locale verso cui il tunnel inoltra il traffico. | Un indirizzo IP valido, per esempio 127.0.0.1 |
port | La porta locale. | Da 1 a 65534 |
path | La cartella locale da condividere. | Obbligatorio solo per File Server |
La risposta è 201 Created con il nuovo tunnel. Annota il suo id e il suo url.
Avvia il tunnel #
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
-H "Authorization: Bearer <YOUR_API_KEY>"La risposta è 204 No Content. Il tunnel diventa raggiungibile al suo url quando il client del dispositivo è connesso. Arrestalo di nuovo con /actions/stop.
Gruppi di endpoint #
Tutti i percorsi qui sotto sono relativi a https://localtonet.com/api/v2.
Tunnel #
| Metodo | Percorso | Scopo |
|---|---|---|
| GET | /tunnels | Elenca tutti i tuoi tunnel. |
| GET | /tunnels/{tunnelId} | Ottieni un tunnel. |
| POST | /tunnels/http/random-subdomain | Crea un tunnel HTTP, File Server o MCP Gateway con un sottodominio casuale. |
| POST | /tunnels/http/custom-subdomain | Creane uno con un sottodominio che scegli tu. |
| POST | /tunnels/http/custom-domain | Creane uno sul tuo dominio. |
| POST | /tunnels/tcp-udp | Crea un tunnel TCP, UDP o TCP e UDP combinato. |
| POST | /tunnels/proxy | Crea un tunnel proxy HTTP, SOCKS5, Shadowsocks o VLESS. |
| POST | /tunnels/proxy/with-detail | Crea un tunnel proxy e restituisci i suoi dettagli di connessione completi. |
| POST | /tunnels/shared-proxy | Crea un tunnel proxy condiviso (a rotazione). |
| POST | /tunnels/{tunnelId}/actions/start | Avvia un tunnel. |
| POST | /tunnels/{tunnelId}/actions/stop | Arresta un tunnel. |
| DELETE | /tunnels/{tunnelId} | Elimina un tunnel definitivamente. |
| PATCH | /tunnels/{tunnelId}/title | Cambia il titolo. |
| PATCH | /tunnels/{tunnelId}/local-ip | Cambia l'indirizzo IP locale. |
| PATCH | /tunnels/{tunnelId}/local-port | Cambia la porta locale. |
| PATCH | /tunnels/{tunnelId}/port-reserved | Attiva o disattiva la riserva della porta di un tunnel TCP/UDP. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | Attiva o disattiva la modalità di connessione legacy. |
| PATCH | /tunnels/{tunnelId}/protocol-type | Cambia il protocollo proxy di un tunnel proxy. |
| GET | /tunnels/{tunnelId}/request-logs | Log recenti delle richieste HTTP di un tunnel HTTP o File Server. |
Operazioni bulk sui tunnel #
| Metodo | Percorso | Scopo |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | Crea più tunnel HTTP con sottodomini casuali. |
| POST | /tunnels/bulk/http/custom-subdomain | Creane più con sottodomini personalizzati. |
| POST | /tunnels/bulk/http/custom-domain | Creane più su domini personalizzati. |
| POST | /tunnels/bulk/tcp-udp | Crea più tunnel TCP/UDP. |
| POST | /tunnels/bulk/proxy | Crea più tunnel proxy. |
| POST | /tunnels/bulk/proxy/with-detail | Crea più tunnel proxy e restituisci i loro dettagli di connessione. |
| POST | /tunnels/bulk/shared-proxy | Crea più tunnel proxy condivisi (a rotazione). |
| POST | /tunnels/bulk/actions/start | Avvia più tunnel. Corpo: un array di ID di tunnel, per esempio [123, 456]. |
| POST | /tunnels/bulk/actions/stop | Arresta più tunnel. Corpo: un array di ID di tunnel. |
| DELETE | /tunnels/bulk | Elimina più tunnel. Corpo: un array di ID di tunnel. |
| PATCH | /tunnels/bulk/protocol-type | Cambia il protocollo proxy di più tunnel proxy. |
Configurazione del tunnel #
Questi endpoint modificano le impostazioni di un singolo tunnel. Iniziano tutti con /tunnels/{tunnelId}. Cosa fa ogni impostazione è descritto nel Riferimento delle impostazioni.
| Metodi | Percorso dopo /tunnels/{tunnelId} | Scopo |
|---|---|---|
| GET, POST, PATCH, DELETE | /ip-restrictions | Elenca, aggiungi, imposta la modalità di consenso o di blocco, oppure elimina tutte le restrizioni IP. Eliminane una con /ip-restrictions/{restrictionId}. |
| GET, POST, PATCH, DELETE | /access-controls | Lo stesso per i controlli di accesso ai percorsi URL. Eliminane uno con /access-controls/{controlId}. |
| GET, PATCH | /headers | Intestazioni HTTP personalizzate. |
| GET, PATCH | /authentication | Autenticazione HTTP Basic. |
| GET, PATCH | /expiration | Data di scadenza del tunnel. |
| GET, PATCH | /server-port | Porta lato server di un tunnel TCP/UDP. |
| GET, PATCH | /http-timeout | Timeout delle richieste HTTP. |
| GET, PATCH | /rate-limit | Limite di velocità. |
| GET, PATCH | /bandwidth-limit | Limite del trasferimento dati totale. |
| GET | /bandwidth-usage | Utilizzo attuale della banda. Azzera il contatore con POST /bandwidth-usage/reset. |
| GET, PATCH | /arguments | Argomenti personalizzati della riga di comando per il tunnel. |
| GET, POST | /shared-proxy-clients | Elenca o aggiungi i client di un tunnel proxy condiviso (a rotazione). Aggiornane o eliminane uno con PATCH o DELETE /shared-proxy-clients/{clientId}. |
| GET | /advanced-settings | Tutte le impostazioni avanzate del tunnel in un'unica risposta. |
| GET, PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | Leggi o attiva/disattiva una singola impostazione avanzata. |
| PATCH | /ssl-stream | Attiva o disattiva l'impostazione del flusso SSL. |
| GET, PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | Leggi o cambia un singolo valore. |
| GET, PUT | /token-groups | I gruppi di token assegnati al tunnel. |
| GET, PATCH | /server | Il server del tunnel. |
AuthToken #
| Metodo | Percorso | Scopo |
|---|---|---|
| GET | /auth-tokens | Elenca i tuoi AuthToken. |
| GET | /auth-tokens/detail | Elenca i tuoi AuthToken con i dettagli. |
| GET | /auth-tokens/{token} | Dettagli di un AuthToken. |
| POST | /auth-tokens | Crea un AuthToken. |
| DELETE | /auth-tokens/{token} | Elimina un AuthToken. |
| GET | /auth-tokens/{token}/tunnels | I tunnel di un AuthToken. |
| GET | /auth-tokens/{token}/ip-history | Cronologia delle modifiche dell'indirizzo IP pubblico del dispositivo. |
| GET, PATCH | /auth-tokens/{token}/airplane-mode-settings | Impostazioni di automazione della modalità aereo. |
| POST | /auth-tokens/{token}/change-ip-links/{airplaneModeSettingId} | Aggiungi un link di cambio IP. |
| DELETE | /auth-tokens/{token}/change-ip-links/{id} | Elimina un link di cambio IP. |
| POST | /auth-tokens/{token}/restart-device-links/{airplaneModeSettingId} | Aggiungi un link di riavvio del dispositivo. |
| DELETE | /auth-tokens/{token}/restart-device-links/{id} | Elimina un link di riavvio del dispositivo. |
| GET, PATCH | /auth-tokens/{token}/arguments | Gli argomenti del client salvati sull'AuthToken. |
Gruppi di token #
| Metodo | Percorso | Scopo |
|---|---|---|
| GET | /token-groups | Elenca i tuoi gruppi di token. |
| GET | /token-groups/{id} | Ottieni un gruppo di token. |
| POST | /token-groups | Crea un gruppo di token. |
| DELETE | /token-groups/{id} | Elimina un gruppo di token. |
| POST | /token-groups/{id}/auth-tokens | Aggiungi un AuthToken al gruppo. |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | Rimuovi un AuthToken dal gruppo. |
Server #
| Metodo | Percorso | Scopo |
|---|---|---|
| GET | /servers | Elenca i server su cui puoi creare tunnel, con il serverCode da usare nelle richieste di creazione. |
Provider SSO #
| Metodo | Percorso | Scopo |
|---|---|---|
| GET | /sso-providers | Elenca i tuoi provider SSO. |
| GET | /sso-providers/default-endpoints | Endpoint predefiniti per un tipo di provider SSO. |
| POST | /sso-providers | Crea o aggiorna un provider SSO. |
| DELETE | /sso-providers/{id} | Elimina un provider SSO. |
| GET | /sso-providers/tunnel/{tunnelId} | I provider SSO configurati per un tunnel. Qui tunnelId è il GUID del tunnel (guidId). |
| PUT | /sso-providers/tunnel/{tunnelId} | Salva i provider SSO di un tunnel. |
Consulta Single Sign-On per sapere cosa fanno i provider.
Accesso VPN #
L'accesso VPN fornisce un profilo di dispositivo WireGuard o OpenVPN su un tunnel proxy; tutto il traffico di quel dispositivo esce attraverso il proxy. Questi endpoint iniziano con /tunnels/{tunnelId}/vpn-access.
| Metodo | Percorso dopo /tunnels/{tunnelId}/vpn-access | Scopo |
|---|---|---|
| GET | (nessuno) | Elenca i dispositivi VPN del tunnel. |
| POST | (nessuno) | Crea un dispositivo VPN. |
| DELETE | /{peerId} | Elimina (revoca) un dispositivo VPN. |
| POST | /{peerId}/regenerate | Rigenera le chiavi di un dispositivo VPN. |
| GET | /{peerId}/config | Scarica il file di configurazione di un dispositivo VPN. |
| GET | /{peerId}/qr | Codice QR della configurazione di un dispositivo WireGuard. |
| GET | /{peerId}/credentials | Nome utente e password di un dispositivo OpenVPN. |
Risoluzione dei problemi #
Ogni richiesta restituisce 401
Controlla l'intestazione: deve essere Authorization: Bearer seguito da uno spazio e dalla chiave, senza virgolette attorno alla chiave. Se hai selezionato Cambia nella scheda Chiave API, la vecchia chiave non funziona più; copia quella nuova.
Non vedo gli AuthToken del mio team
Stai usando la chiave API del tuo account personale. Passa alla dashboard del team e copia lì la chiave API.
Il tunnel è stato creato ma il suo indirizzo non risponde
Un nuovo tunnel è arrestato. Chiama POST /tunnels/{tunnelId}/actions/start e verifica che il client Localtonet del dispositivo sia in esecuzione con l'AuthToken che hai usato.
Ricevo 429 Too Many Requests
Le richieste hanno un limite di frequenza. Attendi, poi invia di nuovo la richiesta e sostituisci i cicli di chiamate singole con una sola richiesta bulk.