Vai al contenuto
Localtonet Localtonet Dashboard

API REST di Localtonet

Aiuto su questa pagina
In questa pagina 8 sezioni
  1. Riferimento interattivo
  2. Prima di iniziare
  3. URL di base e autenticazione
  4. Convenzioni
  5. Errori
  6. Limiti di frequenza
  7. Esempi
  8. Elenca i tuoi tunnel
  9. Crea un tunnel HTTP con un sottodominio casuale
  10. Avvia il tunnel
  11. Gruppi di endpoint
  12. Tunnel
  13. Operazioni bulk sui tunnel
  14. Configurazione del tunnel
  15. AuthToken
  16. Gruppi di token
  17. Server
  18. Provider SSO
  19. Accesso VPN
  20. Risoluzione dei problemi
  21. 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:

URL di base
https://localtonet.com/api/v2

Invia la chiave API come token Bearer nell'intestazione Authorization di ogni richiesta:

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

ArgomentoCome si comporta l'API
FormatoI corpi delle richieste e delle risposte sono in JSON. Invia Content-Type: application/json insieme al corpo.
ID del tunnelIl 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 successo200 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 bulkI percorsi che contengono /bulk/ accettano un array JSON e fino a 100 elementi per richiesta (/tunnels/bulk/protocol-type: fino a 500).
Nuovi tunnelUn 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 #

StatoSignificatoCorpo
400Il 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.
401La chiave API è mancante o non valida.Nessun messaggio specifico
403, 409Restituito 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.
404Il tunnel o l'oggetto non è stato trovato oppure non ti appartiene.Vuoto oppure un oggetto problem
429Troppe 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 #

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

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

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
  }'
CampoSignificatoValori
authTokenL'AuthToken del dispositivo che esegue il tunnel.Obbligatorio
serverCodeIl server, da GET /servers.Obbligatorio
protocolTypeIl tipo di tunnel.1 HTTP, 5 File Server, 24 MCP Gateway
ipL'indirizzo IP locale verso cui il tunnel inoltra il traffico.Un indirizzo IP valido, per esempio 127.0.0.1
portLa porta locale.Da 1 a 65534
pathLa 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 #

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

MetodoPercorsoScopo
GET/tunnelsElenca tutti i tuoi tunnel.
GET/tunnels/{tunnelId}Ottieni un tunnel.
POST/tunnels/http/random-subdomainCrea un tunnel HTTP, File Server o MCP Gateway con un sottodominio casuale.
POST/tunnels/http/custom-subdomainCreane uno con un sottodominio che scegli tu.
POST/tunnels/http/custom-domainCreane uno sul tuo dominio.
POST/tunnels/tcp-udpCrea un tunnel TCP, UDP o TCP e UDP combinato.
POST/tunnels/proxyCrea un tunnel proxy HTTP, SOCKS5, Shadowsocks o VLESS.
POST/tunnels/proxy/with-detailCrea un tunnel proxy e restituisci i suoi dettagli di connessione completi.
POST/tunnels/shared-proxyCrea un tunnel proxy condiviso (a rotazione).
POST/tunnels/{tunnelId}/actions/startAvvia un tunnel.
POST/tunnels/{tunnelId}/actions/stopArresta un tunnel.
DELETE/tunnels/{tunnelId}Elimina un tunnel definitivamente.
PATCH/tunnels/{tunnelId}/titleCambia il titolo.
PATCH/tunnels/{tunnelId}/local-ipCambia l'indirizzo IP locale.
PATCH/tunnels/{tunnelId}/local-portCambia la porta locale.
PATCH/tunnels/{tunnelId}/port-reservedAttiva o disattiva la riserva della porta di un tunnel TCP/UDP.
PATCH/tunnels/{tunnelId}/legacy-connectAttiva o disattiva la modalità di connessione legacy.
PATCH/tunnels/{tunnelId}/protocol-typeCambia il protocollo proxy di un tunnel proxy.
GET/tunnels/{tunnelId}/request-logsLog recenti delle richieste HTTP di un tunnel HTTP o File Server.

Operazioni bulk sui tunnel #

MetodoPercorsoScopo
POST/tunnels/bulk/http/random-subdomainCrea più tunnel HTTP con sottodomini casuali.
POST/tunnels/bulk/http/custom-subdomainCreane più con sottodomini personalizzati.
POST/tunnels/bulk/http/custom-domainCreane più su domini personalizzati.
POST/tunnels/bulk/tcp-udpCrea più tunnel TCP/UDP.
POST/tunnels/bulk/proxyCrea più tunnel proxy.
POST/tunnels/bulk/proxy/with-detailCrea più tunnel proxy e restituisci i loro dettagli di connessione.
POST/tunnels/bulk/shared-proxyCrea più tunnel proxy condivisi (a rotazione).
POST/tunnels/bulk/actions/startAvvia più tunnel. Corpo: un array di ID di tunnel, per esempio [123, 456].
POST/tunnels/bulk/actions/stopArresta più tunnel. Corpo: un array di ID di tunnel.
DELETE/tunnels/bulkElimina più tunnel. Corpo: un array di ID di tunnel.
PATCH/tunnels/bulk/protocol-typeCambia 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.

MetodiPercorso dopo /tunnels/{tunnelId}Scopo
GET, POST, PATCH, DELETE/ip-restrictionsElenca, 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-controlsLo stesso per i controlli di accesso ai percorsi URL. Eliminane uno con /access-controls/{controlId}.
GET, PATCH/headersIntestazioni HTTP personalizzate.
GET, PATCH/authenticationAutenticazione HTTP Basic.
GET, PATCH/expirationData di scadenza del tunnel.
GET, PATCH/server-portPorta lato server di un tunnel TCP/UDP.
GET, PATCH/http-timeoutTimeout delle richieste HTTP.
GET, PATCH/rate-limitLimite di velocità.
GET, PATCH/bandwidth-limitLimite del trasferimento dati totale.
GET/bandwidth-usageUtilizzo attuale della banda. Azzera il contatore con POST /bandwidth-usage/reset.
GET, PATCH/argumentsArgomenti personalizzati della riga di comando per il tunnel.
GET, POST/shared-proxy-clientsElenca 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-settingsTutte le impostazioni avanzate del tunnel in un'unica risposta.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3Leggi o attiva/disattiva una singola impostazione avanzata.
PATCH/ssl-streamAttiva o disattiva l'impostazione del flusso SSL.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessLeggi o cambia un singolo valore.
GET, PUT/token-groupsI gruppi di token assegnati al tunnel.
GET, PATCH/serverIl server del tunnel.

AuthToken #

MetodoPercorsoScopo
GET/auth-tokensElenca i tuoi AuthToken.
GET/auth-tokens/detailElenca i tuoi AuthToken con i dettagli.
GET/auth-tokens/{token}Dettagli di un AuthToken.
POST/auth-tokensCrea un AuthToken.
DELETE/auth-tokens/{token}Elimina un AuthToken.
GET/auth-tokens/{token}/tunnelsI tunnel di un AuthToken.
GET/auth-tokens/{token}/ip-historyCronologia delle modifiche dell'indirizzo IP pubblico del dispositivo.
GET, PATCH/auth-tokens/{token}/airplane-mode-settingsImpostazioni 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}/argumentsGli argomenti del client salvati sull'AuthToken.

Gruppi di token #

MetodoPercorsoScopo
GET/token-groupsElenca i tuoi gruppi di token.
GET/token-groups/{id}Ottieni un gruppo di token.
POST/token-groupsCrea un gruppo di token.
DELETE/token-groups/{id}Elimina un gruppo di token.
POST/token-groups/{id}/auth-tokensAggiungi un AuthToken al gruppo.
DELETE/token-groups/{id}/auth-tokens/{tokenId}Rimuovi un AuthToken dal gruppo.

Server #

MetodoPercorsoScopo
GET/serversElenca i server su cui puoi creare tunnel, con il serverCode da usare nelle richieste di creazione.

Provider SSO #

MetodoPercorsoScopo
GET/sso-providersElenca i tuoi provider SSO.
GET/sso-providers/default-endpointsEndpoint predefiniti per un tipo di provider SSO.
POST/sso-providersCrea 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.

MetodoPercorso dopo /tunnels/{tunnelId}/vpn-accessScopo
GET(nessuno)Elenca i dispositivi VPN del tunnel.
POST(nessuno)Crea un dispositivo VPN.
DELETE/{peerId}Elimina (revoca) un dispositivo VPN.
POST/{peerId}/regenerateRigenera le chiavi di un dispositivo VPN.
GET/{peerId}/configScarica il file di configurazione di un dispositivo VPN.
GET/{peerId}/qrCodice QR della configurazione di un dispositivo WireGuard.
GET/{peerId}/credentialsNome 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.

Supporto