API REST do Localtonet
Nesta página 8 seções
- Referência interativa
- Antes de começar
- URL base e autenticação
- Convenções
- Erros
- Limites de taxa
- Exemplos
- Listar seus túneis
- Criar um túnel HTTP com um subdomínio aleatório
- Inicie o túnel
- Grupos de endpoints
- Túneis
- Operações de túnel em lote
- Configuração do túnel
- AuthTokens
- Grupos de tokens
- Servidores
- Provedores de SSO
- Acesso VPN
- Solução de problemas
- Páginas relacionadas
A API REST v2 faz o que o painel faz com túneis: criar, iniciar, parar, excluir e configurá-los, além de gerenciar AuthTokens, grupos de tokens e provedores de SSO. Você autentica cada requisição com a sua chave de API.
Referência interativa #
Todos os endpoints, com seus modelos de requisição e resposta e um formulário para testá-los, estão na referência interativa:
- localtonet.com/api: API v2, a versão atual. Você também chega a ela pelo botão Interface da API no painel.
- localtonet.com/api/v1: API v1, mantida para integrações existentes. Use a v2 em trabalhos novos.
Esta página traz as convenções e uma visão geral dos grupos de endpoints. Para os campos exatos de uma requisição, abra o endpoint na referência.
Antes de começar #
- Sua chave de API. Abra o Painel e use Copiar no cartão Chave de API. Veja Conta e segurança.
- Para criar túneis: um AuthToken do dispositivo que vai executar o túnel e um cliente do Localtonet conectado com esse token. Veja AuthTokens.
Mantenha sua chave de API em sigilo. Quem a tiver pode criar, alterar e excluir seus túneis e tokens. Alterar no cartão Chave de API cria uma nova chave e invalida a antiga.
URL base e autenticação #
Todos os endpoints da v2 começam com:
https://localtonet.com/api/v2Envie a chave de API como token Bearer no cabeçalho Authorization de cada requisição:
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>Uma chave de API copiada em um painel de equipe lista seus AuthTokens e túneis nessa equipe; a chave da sua própria conta lista os AuthTokens que não pertencem a nenhuma equipe.
Convenções #
| Tópico | Como a API se comporta |
|---|---|
| Formato | Os corpos de requisição e de resposta são JSON. Envie Content-Type: application/json junto com um corpo. |
| ID do túnel | O tunnelId em um caminho é o id numérico do túnel, como retornado pelos endpoints de listagem e de criação. |
| AuthToken em um caminho | {token} é a própria string do AuthToken. |
| Códigos de sucesso | 200 com corpo para leituras, 201 para a maioria das criações (os endpoints de criação de túnel retornam o novo túnel), 204 sem corpo para a maioria das ações e atualizações. A referência mostra a resposta de cada endpoint. |
| Endpoints em lote | Os caminhos que contêm /bulk/ recebem um array JSON e aceitam até 100 itens por requisição (/tunnels/bulk/protocol-type: até 500). |
| Novos túneis | Um túnel que você cria ainda não está em execução. Inicie-o com a ação de iniciar. Somente os endpoints proxy/with-detail podem iniciar o túnel na mesma chamada, com isStartAfterCreate. |
Erros #
| Status | Significado | Corpo |
|---|---|---|
400 | O corpo da requisição não é válido, ou a operação foi recusada, por exemplo por causa de um limite do seu plano. | Na maioria dos endpoints, um objeto de problema em JSON; title contém a mensagem. Os erros de validação e os erros dos endpoints em lote são listados em errors. |
401 | A chave de API está ausente ou é inválida. | Nenhuma mensagem específica |
403, 409 | Retornado por alguns endpoints de configuração de túnel e de acesso VPN quando a alteração não é permitida ou entra em conflito com a configuração atual. | Um objeto de problema com a mensagem em title. |
404 | O túnel ou objeto não foi encontrado ou não pertence a você. | Vazio ou um objeto de problema |
429 | Requisições demais. | Veja os limites de taxa abaixo. |
Limites de taxa #
As requisições têm limite de taxa. Uma requisição acima do limite recebe 429 Too Many Requests como resposta. Aguarde e envie de novo; use os endpoints em lote em vez de muitas chamadas individuais.
Exemplos #
Substitua <YOUR_API_KEY> pela sua chave de API e <YOUR_TOKEN> pelo AuthToken do dispositivo.
Listar seus túneis #
curl https://localtonet.com/api/v2/tunnels \
-H "Authorization: Bearer <YOUR_API_KEY>"A resposta é um array JSON com um objeto por túnel. Entre os campos estão id, title, url (o endereço público), protocolType, authToken, serverId, clientIp e clientPort (o destino local), status e connectionStatus. Se você ainda não tem túneis, a resposta é 404 em vez de um array vazio.
Criar um túnel HTTP com um subdomínio aleatório #
Primeiro obtenha o código do servidor que você quer usar:
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"Cada entrada tem um serverCode, um serverName e um serverDomain. Em seguida, crie o túnel. Este exemplo encaminha para um aplicativo web na porta 3000 do 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 | Significado | Valores |
|---|---|---|
authToken | O AuthToken do dispositivo que executa o túnel. | Obrigatório |
serverCode | O servidor, obtido de GET /servers. | Obrigatório |
protocolType | O tipo de túnel. | 1 HTTP, 5 File Server, 24 MCP Gateway |
ip | O endereço IP local para o qual o túnel encaminha. | Um endereço IP válido, por exemplo 127.0.0.1 |
port | A porta local. | 1 a 65534 |
path | A pasta local a compartilhar. | Obrigatório somente para File Server |
A resposta é 201 Created com o novo túnel. Anote o id e a url dele.
Inicie o túnel #
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
-H "Authorization: Bearer <YOUR_API_KEY>"A resposta é 204 No Content. O túnel passa a ser acessível em sua url quando o cliente do dispositivo está conectado. Para pará-lo de novo, use /actions/stop.
Grupos de endpoints #
Todos os caminhos abaixo são relativos a https://localtonet.com/api/v2.
Túneis #
| Método | Caminho | Finalidade |
|---|---|---|
| GET | /tunnels | Lista todos os seus túneis. |
| GET | /tunnels/{tunnelId} | Obtém um túnel. |
| POST | /tunnels/http/random-subdomain | Cria um túnel HTTP, File Server ou MCP Gateway com um subdomínio aleatório. |
| POST | /tunnels/http/custom-subdomain | Cria um com um subdomínio de sua escolha. |
| POST | /tunnels/http/custom-domain | Cria um no seu próprio domínio. |
| POST | /tunnels/tcp-udp | Cria um túnel TCP, UDP ou TCP e UDP combinados. |
| POST | /tunnels/proxy | Cria um túnel de proxy HTTP, SOCKS5, Shadowsocks ou VLESS. |
| POST | /tunnels/proxy/with-detail | Cria um túnel de proxy e retorna todos os detalhes de conexão. |
| POST | /tunnels/shared-proxy | Cria um túnel de proxy compartilhado (rotativo). |
| POST | /tunnels/{tunnelId}/actions/start | Inicia um túnel. |
| POST | /tunnels/{tunnelId}/actions/stop | Para um túnel. |
| DELETE | /tunnels/{tunnelId} | Exclui um túnel permanentemente. |
| PATCH | /tunnels/{tunnelId}/title | Altera o título. |
| PATCH | /tunnels/{tunnelId}/local-ip | Altera o endereço IP local. |
| PATCH | /tunnels/{tunnelId}/local-port | Altera a porta local. |
| PATCH | /tunnels/{tunnelId}/port-reserved | Ativa ou desativa a reserva de porta de um túnel TCP/UDP. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | Ativa ou desativa o modo de conexão legado. |
| PATCH | /tunnels/{tunnelId}/protocol-type | Altera o protocolo de proxy de um túnel de proxy. |
| GET | /tunnels/{tunnelId}/request-logs | Logs recentes de requisições HTTP de um túnel HTTP ou File Server. |
Operações de túnel em lote #
| Método | Caminho | Finalidade |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | Cria vários túneis HTTP com subdomínios aleatórios. |
| POST | /tunnels/bulk/http/custom-subdomain | Cria vários com subdomínios personalizados. |
| POST | /tunnels/bulk/http/custom-domain | Cria vários em domínios personalizados. |
| POST | /tunnels/bulk/tcp-udp | Cria vários túneis TCP/UDP. |
| POST | /tunnels/bulk/proxy | Cria vários túneis de proxy. |
| POST | /tunnels/bulk/proxy/with-detail | Cria vários túneis de proxy e retorna os detalhes de conexão deles. |
| POST | /tunnels/bulk/shared-proxy | Cria vários túneis de proxy compartilhado (rotativo). |
| POST | /tunnels/bulk/actions/start | Inicia vários túneis. Corpo: um array de IDs de túnel, por exemplo [123, 456]. |
| POST | /tunnels/bulk/actions/stop | Para vários túneis. Corpo: um array de IDs de túnel. |
| DELETE | /tunnels/bulk | Exclui vários túneis. Corpo: um array de IDs de túnel. |
| PATCH | /tunnels/bulk/protocol-type | Altera o protocolo de proxy de vários túneis de proxy. |
Configuração do túnel #
Estes endpoints alteram as configurações de um túnel. Todos começam com /tunnels/{tunnelId}. O que cada configuração faz está descrito na Referência de configurações.
| Métodos | Caminho após /tunnels/{tunnelId} | Finalidade |
|---|---|---|
| GET, POST, PATCH, DELETE | /ip-restrictions | Lista, adiciona, define o modo de permitir ou negar, ou exclui todas as restrições de IP. Exclua uma com /ip-restrictions/{restrictionId}. |
| GET, POST, PATCH, DELETE | /access-controls | O mesmo para os controles de acesso por caminho de URL. Exclua um com /access-controls/{controlId}. |
| GET, PATCH | /headers | Cabeçalhos HTTP personalizados. |
| GET, PATCH | /authentication | Autenticação básica HTTP. |
| GET, PATCH | /expiration | Data de expiração do túnel. |
| GET, PATCH | /server-port | Porta do lado do servidor de um túnel TCP/UDP. |
| GET, PATCH | /http-timeout | Tempo limite de requisição HTTP. |
| GET, PATCH | /rate-limit | Limite de velocidade. |
| GET, PATCH | /bandwidth-limit | Limite total de transferência de dados. |
| GET | /bandwidth-usage | Uso atual de banda. Zere o contador com POST /bandwidth-usage/reset. |
| GET, PATCH | /arguments | Argumentos de linha de comando personalizados para o túnel. |
| GET, POST | /shared-proxy-clients | Lista ou adiciona clientes de um túnel de proxy compartilhado (rotativo). Atualize ou exclua um com PATCH ou DELETE /shared-proxy-clients/{clientId}. |
| GET | /advanced-settings | Todas as configurações avançadas do túnel em uma só resposta. |
| GET, PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | Lê ou alterna uma configuração avançada. |
| PATCH | /ssl-stream | Alterna a configuração de fluxo SSL. |
| GET, PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | Lê ou altera um valor. |
| GET, PUT | /token-groups | Os grupos de tokens atribuídos ao túnel. |
| GET, PATCH | /server | O servidor do túnel. |
AuthTokens #
| Método | Caminho | Finalidade |
|---|---|---|
| GET | /auth-tokens | Lista seus AuthTokens. |
| GET | /auth-tokens/detail | Lista seus AuthTokens com detalhes. |
| GET | /auth-tokens/{token} | Detalhes de um AuthToken. |
| POST | /auth-tokens | Cria um AuthToken. |
| DELETE | /auth-tokens/{token} | Exclui um AuthToken. |
| GET | /auth-tokens/{token}/tunnels | Os túneis de um AuthToken. |
| GET | /auth-tokens/{token}/ip-history | Histórico de alterações do endereço IP público do dispositivo. |
| GET, PATCH | /auth-tokens/{token}/airplane-mode-settings | Configurações de automação do modo avião. |
| POST | /auth-tokens/{token}/change-ip-links/{airplaneModeSettingId} | Adiciona um link de alteração de IP. |
| DELETE | /auth-tokens/{token}/change-ip-links/{id} | Exclui um link de alteração de IP. |
| POST | /auth-tokens/{token}/restart-device-links/{airplaneModeSettingId} | Adiciona um link de reinício do dispositivo. |
| DELETE | /auth-tokens/{token}/restart-device-links/{id} | Exclui um link de reinício do dispositivo. |
| GET, PATCH | /auth-tokens/{token}/arguments | Os argumentos do cliente salvos no AuthToken. |
Grupos de tokens #
| Método | Caminho | Finalidade |
|---|---|---|
| GET | /token-groups | Lista seus grupos de tokens. |
| GET | /token-groups/{id} | Obtém um grupo de tokens. |
| POST | /token-groups | Cria um grupo de tokens. |
| DELETE | /token-groups/{id} | Exclui um grupo de tokens. |
| POST | /token-groups/{id}/auth-tokens | Adiciona um AuthToken ao grupo. |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | Remove um AuthToken do grupo. |
Servidores #
| Método | Caminho | Finalidade |
|---|---|---|
| GET | /servers | Lista os servidores em que você pode criar túneis, com o serverCode a usar nas requisições de criação. |
Provedores de SSO #
| Método | Caminho | Finalidade |
|---|---|---|
| GET | /sso-providers | Lista seus provedores de SSO. |
| GET | /sso-providers/default-endpoints | Endpoints padrão para um tipo de provedor de SSO. |
| POST | /sso-providers | Cria ou atualiza um provedor de SSO. |
| DELETE | /sso-providers/{id} | Exclui um provedor de SSO. |
| GET | /sso-providers/tunnel/{tunnelId} | Os provedores de SSO configurados para um túnel. Aqui, tunnelId é o GUID do túnel (guidId). |
| PUT | /sso-providers/tunnel/{tunnelId} | Salva os provedores de SSO de um túnel. |
Veja Login único (SSO) para saber o que os provedores fazem.
Acesso VPN #
O acesso VPN dá um perfil de dispositivo WireGuard ou OpenVPN em um túnel de proxy; todo o tráfego desse dispositivo sai pelo proxy. Estes endpoints começam com /tunnels/{tunnelId}/vpn-access.
| Método | Caminho após /tunnels/{tunnelId}/vpn-access | Finalidade |
|---|---|---|
| GET | (nenhum) | Lista os dispositivos VPN do túnel. |
| POST | (nenhum) | Cria um dispositivo VPN. |
| DELETE | /{peerId} | Exclui (revoga) um dispositivo VPN. |
| POST | /{peerId}/regenerate | Gera de novo as chaves de um dispositivo VPN. |
| GET | /{peerId}/config | Baixa o arquivo de configuração de um dispositivo VPN. |
| GET | /{peerId}/qr | Código QR da configuração de um dispositivo WireGuard. |
| GET | /{peerId}/credentials | Nome de usuário e senha de um dispositivo OpenVPN. |
Solução de problemas #
Toda requisição retorna 401
Verifique o cabeçalho: ele deve ser Authorization: Bearer seguido de um espaço e da chave, sem aspas ao redor da chave. Se você selecionou Alterar no cartão Chave de API, a chave antiga deixa de funcionar; copie a nova.
Não vejo os AuthTokens da minha equipe
Você está usando a chave de API da sua própria conta. Mude para o painel da equipe e copie a chave de API de lá.
O túnel foi criado, mas o endereço dele não responde
Um túnel novo fica parado. Chame POST /tunnels/{tunnelId}/actions/start e verifique se o cliente do Localtonet do dispositivo está em execução com o AuthToken que você usou.
Recebo 429 Too Many Requests
As requisições têm limite de taxa. Aguarde, envie a requisição de novo e troque os laços de chamadas individuais por uma única requisição em lote.