Ir para o conteúdo
Localtonet Localtonet Painel

API REST do Localtonet

Ajuda com esta página
Nesta página 8 seções
  1. Referência interativa
  2. Antes de começar
  3. URL base e autenticação
  4. Convenções
  5. Erros
  6. Limites de taxa
  7. Exemplos
  8. Listar seus túneis
  9. Criar um túnel HTTP com um subdomínio aleatório
  10. Inicie o túnel
  11. Grupos de endpoints
  12. Túneis
  13. Operações de túnel em lote
  14. Configuração do túnel
  15. AuthTokens
  16. Grupos de tokens
  17. Servidores
  18. Provedores de SSO
  19. Acesso VPN
  20. Solução de problemas
  21. 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:

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

Envie a chave de API como token Bearer no cabeçalho Authorization de cada requisição:

HTTP
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ópicoComo a API se comporta
FormatoOs corpos de requisição e de resposta são JSON. Envie Content-Type: application/json junto com um corpo.
ID do túnelO 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 sucesso200 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 loteOs 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úneisUm 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 #

StatusSignificadoCorpo
400O 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.
401A chave de API está ausente ou é inválida.Nenhuma mensagem específica
403, 409Retornado 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.
404O túnel ou objeto não foi encontrado ou não pertence a você.Vazio ou um objeto de problema
429Requisiçõ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 #

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

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

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
  }'
CampoSignificadoValores
authTokenO AuthToken do dispositivo que executa o túnel.Obrigatório
serverCodeO servidor, obtido de GET /servers.Obrigatório
protocolTypeO tipo de túnel.1 HTTP, 5 File Server, 24 MCP Gateway
ipO endereço IP local para o qual o túnel encaminha.Um endereço IP válido, por exemplo 127.0.0.1
portA porta local.1 a 65534
pathA 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 #

Bash
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étodoCaminhoFinalidade
GET/tunnelsLista todos os seus túneis.
GET/tunnels/{tunnelId}Obtém um túnel.
POST/tunnels/http/random-subdomainCria um túnel HTTP, File Server ou MCP Gateway com um subdomínio aleatório.
POST/tunnels/http/custom-subdomainCria um com um subdomínio de sua escolha.
POST/tunnels/http/custom-domainCria um no seu próprio domínio.
POST/tunnels/tcp-udpCria um túnel TCP, UDP ou TCP e UDP combinados.
POST/tunnels/proxyCria um túnel de proxy HTTP, SOCKS5, Shadowsocks ou VLESS.
POST/tunnels/proxy/with-detailCria um túnel de proxy e retorna todos os detalhes de conexão.
POST/tunnels/shared-proxyCria um túnel de proxy compartilhado (rotativo).
POST/tunnels/{tunnelId}/actions/startInicia um túnel.
POST/tunnels/{tunnelId}/actions/stopPara um túnel.
DELETE/tunnels/{tunnelId}Exclui um túnel permanentemente.
PATCH/tunnels/{tunnelId}/titleAltera o título.
PATCH/tunnels/{tunnelId}/local-ipAltera o endereço IP local.
PATCH/tunnels/{tunnelId}/local-portAltera a porta local.
PATCH/tunnels/{tunnelId}/port-reservedAtiva ou desativa a reserva de porta de um túnel TCP/UDP.
PATCH/tunnels/{tunnelId}/legacy-connectAtiva ou desativa o modo de conexão legado.
PATCH/tunnels/{tunnelId}/protocol-typeAltera o protocolo de proxy de um túnel de proxy.
GET/tunnels/{tunnelId}/request-logsLogs recentes de requisições HTTP de um túnel HTTP ou File Server.

Operações de túnel em lote #

MétodoCaminhoFinalidade
POST/tunnels/bulk/http/random-subdomainCria vários túneis HTTP com subdomínios aleatórios.
POST/tunnels/bulk/http/custom-subdomainCria vários com subdomínios personalizados.
POST/tunnels/bulk/http/custom-domainCria vários em domínios personalizados.
POST/tunnels/bulk/tcp-udpCria vários túneis TCP/UDP.
POST/tunnels/bulk/proxyCria vários túneis de proxy.
POST/tunnels/bulk/proxy/with-detailCria vários túneis de proxy e retorna os detalhes de conexão deles.
POST/tunnels/bulk/shared-proxyCria vários túneis de proxy compartilhado (rotativo).
POST/tunnels/bulk/actions/startInicia vários túneis. Corpo: um array de IDs de túnel, por exemplo [123, 456].
POST/tunnels/bulk/actions/stopPara vários túneis. Corpo: um array de IDs de túnel.
DELETE/tunnels/bulkExclui vários túneis. Corpo: um array de IDs de túnel.
PATCH/tunnels/bulk/protocol-typeAltera 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étodosCaminho após /tunnels/{tunnelId}Finalidade
GET, POST, PATCH, DELETE/ip-restrictionsLista, 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-controlsO mesmo para os controles de acesso por caminho de URL. Exclua um com /access-controls/{controlId}.
GET, PATCH/headersCabeçalhos HTTP personalizados.
GET, PATCH/authenticationAutenticação básica HTTP.
GET, PATCH/expirationData de expiração do túnel.
GET, PATCH/server-portPorta do lado do servidor de um túnel TCP/UDP.
GET, PATCH/http-timeoutTempo limite de requisição HTTP.
GET, PATCH/rate-limitLimite de velocidade.
GET, PATCH/bandwidth-limitLimite total de transferência de dados.
GET/bandwidth-usageUso atual de banda. Zere o contador com POST /bandwidth-usage/reset.
GET, PATCH/argumentsArgumentos de linha de comando personalizados para o túnel.
GET, POST/shared-proxy-clientsLista 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-settingsTodas as configurações avançadas do túnel em uma só resposta.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3Lê ou alterna uma configuração avançada.
PATCH/ssl-streamAlterna a configuração de fluxo SSL.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessLê ou altera um valor.
GET, PUT/token-groupsOs grupos de tokens atribuídos ao túnel.
GET, PATCH/serverO servidor do túnel.

AuthTokens #

MétodoCaminhoFinalidade
GET/auth-tokensLista seus AuthTokens.
GET/auth-tokens/detailLista seus AuthTokens com detalhes.
GET/auth-tokens/{token}Detalhes de um AuthToken.
POST/auth-tokensCria um AuthToken.
DELETE/auth-tokens/{token}Exclui um AuthToken.
GET/auth-tokens/{token}/tunnelsOs túneis de um AuthToken.
GET/auth-tokens/{token}/ip-historyHistórico de alterações do endereço IP público do dispositivo.
GET, PATCH/auth-tokens/{token}/airplane-mode-settingsConfiguraçõ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}/argumentsOs argumentos do cliente salvos no AuthToken.

Grupos de tokens #

MétodoCaminhoFinalidade
GET/token-groupsLista seus grupos de tokens.
GET/token-groups/{id}Obtém um grupo de tokens.
POST/token-groupsCria um grupo de tokens.
DELETE/token-groups/{id}Exclui um grupo de tokens.
POST/token-groups/{id}/auth-tokensAdiciona um AuthToken ao grupo.
DELETE/token-groups/{id}/auth-tokens/{tokenId}Remove um AuthToken do grupo.

Servidores #

MétodoCaminhoFinalidade
GET/serversLista os servidores em que você pode criar túneis, com o serverCode a usar nas requisições de criação.

Provedores de SSO #

MétodoCaminhoFinalidade
GET/sso-providersLista seus provedores de SSO.
GET/sso-providers/default-endpointsEndpoints padrão para um tipo de provedor de SSO.
POST/sso-providersCria 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étodoCaminho após /tunnels/{tunnelId}/vpn-accessFinalidade
GET(nenhum)Lista os dispositivos VPN do túnel.
POST(nenhum)Cria um dispositivo VPN.
DELETE/{peerId}Exclui (revoga) um dispositivo VPN.
POST/{peerId}/regenerateGera de novo as chaves de um dispositivo VPN.
GET/{peerId}/configBaixa o arquivo de configuração de um dispositivo VPN.
GET/{peerId}/qrCódigo QR da configuração de um dispositivo WireGuard.
GET/{peerId}/credentialsNome 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.

Suporte