Saltar al contenido
Localtonet Localtonet Panel

API REST de Localtonet

Ayuda con esta página
En esta página 8 secciones
  1. Referencia interactiva
  2. Antes de empezar
  3. URL base y autenticación
  4. Convenciones
  5. Errores
  6. Límites de frecuencia
  7. Ejemplos
  8. Lista tus túneles
  9. Crea un túnel HTTP con un subdominio aleatorio
  10. Inicia el túnel
  11. Grupos de endpoints
  12. Túneles
  13. Operaciones masivas con túneles
  14. Configuración del túnel
  15. AuthTokens
  16. Grupos de tokens
  17. Servidores
  18. Proveedores de SSO
  19. Acceso VPN
  20. Solución de problemas
  21. Páginas relacionadas

La API REST v2 hace con los túneles lo mismo que el panel: crearlos, iniciarlos, detenerlos, eliminarlos y configurarlos, además de gestionar AuthTokens, grupos de tokens y proveedores de SSO. Autenticas cada solicitud con tu clave de API.

Referencia interactiva #

Todos los endpoints, con sus modelos de solicitud y respuesta y un formulario para probarlos, están en la referencia interactiva:

  • localtonet.com/api: API v2, la versión actual. También se accede a ella con el botón Interfaz de API del panel.
  • localtonet.com/api/v1: API v1, que se mantiene para integraciones existentes. Usa la v2 para trabajos nuevos.

Esta página te da las convenciones y una visión general de los grupos de endpoints. Para ver los campos exactos de una solicitud, abre el endpoint en la referencia.

Antes de empezar #

  • Tu clave de API. Abre el Panel y usa Copiar en la tarjeta Clave de API. Consulta Cuenta y seguridad.
  • Para crear túneles: un AuthToken del dispositivo que ejecutará el túnel y un cliente de Localtonet conectado con ese token. Consulta AuthTokens.

Mantén tu clave de API en privado. Quien la tenga puede crear, modificar y eliminar tus túneles y tokens. Cambiar, en la tarjeta Clave de API, crea una clave nueva e invalida la anterior.

URL base y autenticación #

Todos los endpoints de la v2 empiezan con:

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

Envía la clave de API como token Bearer en la cabecera Authorization de cada solicitud:

HTTP
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>

Una clave de API copiada en un panel de equipo lista tus AuthTokens y túneles de ese equipo; la clave de tu propia cuenta lista los AuthTokens que no pertenecen a ningún equipo.

Convenciones #

TemaCómo se comporta la API
FormatoLos cuerpos de solicitud y de respuesta son JSON. Envía Content-Type: application/json cuando haya cuerpo.
ID del túnelEl tunnelId de una ruta es el id numérico del túnel, tal como lo devuelven los endpoints de listado y de creación.
AuthToken en una ruta{token} es la propia cadena del AuthToken.
Códigos de éxito200 con cuerpo para las lecturas, 201 para la mayoría de las creaciones (los endpoints de creación de túneles devuelven el túnel nuevo), 204 sin cuerpo para la mayoría de las acciones y actualizaciones. La referencia muestra la respuesta de cada endpoint.
Endpoints masivosLas rutas que contienen /bulk/ aceptan un array JSON con hasta 100 elementos por solicitud (/tunnels/bulk/protocol-type: hasta 500).
Túneles nuevosUn túnel que creas todavía no está en ejecución. Inícialo con la acción de inicio. Solo los endpoints proxy/with-detail pueden iniciar el túnel en la misma llamada, con isStartAfterCreate.

Errores #

EstadoSignificadoCuerpo
400El cuerpo de la solicitud no es válido o se rechazó la operación, por ejemplo por un límite de tu plan.En la mayoría de los endpoints, un objeto de problema en JSON; title contiene el mensaje. Los errores de validación y los de los endpoints masivos se enumeran en errors.
401Falta la clave de API o no es válida.Sin mensaje específico
403, 409Lo devuelven algunos endpoints de configuración de túneles y de acceso VPN cuando el cambio no está permitido o entra en conflicto con la configuración actual.Un objeto de problema con el mensaje en title.
404No se encontró el túnel o el objeto, o no te pertenece.Vacío o un objeto de problema
429Demasiadas solicitudes.Consulta los límites de frecuencia más abajo.

Límites de frecuencia #

Las solicitudes tienen un límite de frecuencia. Una solicitud que lo supera recibe 429 Too Many Requests. Espera y vuelve a enviarla; usa los endpoints masivos en lugar de muchas llamadas individuales.

Ejemplos #

Sustituye <YOUR_API_KEY> por tu clave de API y <YOUR_TOKEN> por el AuthToken del dispositivo.

Lista tus túneles #

Bash
curl https://localtonet.com/api/v2/tunnels \
  -H "Authorization: Bearer <YOUR_API_KEY>"

La respuesta es un array JSON con un objeto por túnel. Entre sus campos están id, title, url (la dirección pública), protocolType, authToken, serverId, clientIp y clientPort (el destino local), status y connectionStatus. Si todavía no tienes túneles, la respuesta es 404 en lugar de un array vacío.

Crea un túnel HTTP con un subdominio aleatorio #

Primero obtén el código del servidor que quieres usar:

Bash
curl https://localtonet.com/api/v2/servers \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Cada entrada tiene un serverCode, un serverName y un serverDomain. Luego crea el túnel. Este ejemplo reenvía a una aplicación web en el puerto 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
  }'
CampoSignificadoValores
authTokenEl AuthToken del dispositivo que ejecuta el túnel.Obligatorio
serverCodeEl servidor, de GET /servers.Obligatorio
protocolTypeEl tipo de túnel.1 HTTP, 5 File Server, 24 MCP Gateway
ipLa dirección IP local a la que reenvía el túnel.Una dirección IP válida, por ejemplo 127.0.0.1
portEl puerto local.De 1 a 65534
pathLa carpeta local que se comparte.Obligatorio solo para File Server

La respuesta es 201 Created con el túnel nuevo. Anota su id y su url.

Inicia el túnel #

Bash
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
  -H "Authorization: Bearer <YOUR_API_KEY>"

La respuesta es 204 No Content. El túnel pasa a ser accesible en su url cuando el cliente del dispositivo está conectado. Vuelve a detenerlo con /actions/stop.

Grupos de endpoints #

Todas las rutas siguientes son relativas a https://localtonet.com/api/v2.

Túneles #

MétodoRutaFinalidad
GET/tunnelsLista todos tus túneles.
GET/tunnels/{tunnelId}Obtiene un túnel.
POST/tunnels/http/random-subdomainCrea un túnel HTTP, File Server o MCP Gateway con un subdominio aleatorio.
POST/tunnels/http/custom-subdomainCrea uno con un subdominio que eliges.
POST/tunnels/http/custom-domainCrea uno en tu propio dominio.
POST/tunnels/tcp-udpCrea un túnel TCP, UDP o combinado TCP y UDP.
POST/tunnels/proxyCrea un túnel proxy HTTP, SOCKS5, Shadowsocks o VLESS.
POST/tunnels/proxy/with-detailCrea un túnel proxy y devuelve sus datos de conexión completos.
POST/tunnels/shared-proxyCrea un túnel proxy compartido (rotativo).
POST/tunnels/{tunnelId}/actions/startInicia un túnel.
POST/tunnels/{tunnelId}/actions/stopDetiene un túnel.
DELETE/tunnels/{tunnelId}Elimina un túnel de forma permanente.
PATCH/tunnels/{tunnelId}/titleCambia el título.
PATCH/tunnels/{tunnelId}/local-ipCambia la dirección IP local.
PATCH/tunnels/{tunnelId}/local-portCambia el puerto local.
PATCH/tunnels/{tunnelId}/port-reservedActiva o desactiva la reserva de puerto de un túnel TCP/UDP.
PATCH/tunnels/{tunnelId}/legacy-connectActiva o desactiva el modo de conexión heredado.
PATCH/tunnels/{tunnelId}/protocol-typeCambia el protocolo proxy de un túnel proxy.
GET/tunnels/{tunnelId}/request-logsRegistros de las solicitudes HTTP recientes de un túnel HTTP o File Server.

Operaciones masivas con túneles #

MétodoRutaFinalidad
POST/tunnels/bulk/http/random-subdomainCrea varios túneles HTTP con subdominios aleatorios.
POST/tunnels/bulk/http/custom-subdomainCrea varios con subdominios personalizados.
POST/tunnels/bulk/http/custom-domainCrea varios en dominios personalizados.
POST/tunnels/bulk/tcp-udpCrea varios túneles TCP/UDP.
POST/tunnels/bulk/proxyCrea varios túneles proxy.
POST/tunnels/bulk/proxy/with-detailCrea varios túneles proxy y devuelve sus datos de conexión.
POST/tunnels/bulk/shared-proxyCrea varios túneles proxy compartidos (rotativos).
POST/tunnels/bulk/actions/startInicia varios túneles. Cuerpo: un array de ID de túneles, por ejemplo [123, 456].
POST/tunnels/bulk/actions/stopDetiene varios túneles. Cuerpo: un array de ID de túneles.
DELETE/tunnels/bulkElimina varios túneles. Cuerpo: un array de ID de túneles.
PATCH/tunnels/bulk/protocol-typeCambia el protocolo proxy de varios túneles proxy.

Configuración del túnel #

Estos endpoints cambian los ajustes de un túnel. Todos empiezan con /tunnels/{tunnelId}. Lo que hace cada ajuste se describe en la Referencia de configuración.

MétodosRuta después de /tunnels/{tunnelId}Finalidad
GET, POST, PATCH, DELETE/ip-restrictionsLista, añade, establece el modo de permitir o denegar, o elimina todas las restricciones de IP. Elimina una con /ip-restrictions/{restrictionId}.
GET, POST, PATCH, DELETE/access-controlsLo mismo para los controles de acceso por ruta URL. Elimina uno con /access-controls/{controlId}.
GET, PATCH/headersCabeceras HTTP personalizadas.
GET, PATCH/authenticationAutenticación básica HTTP.
GET, PATCH/expirationFecha de caducidad del túnel.
GET, PATCH/server-portPuerto del lado del servidor de un túnel TCP/UDP.
GET, PATCH/http-timeoutTiempo de espera de las solicitudes HTTP.
GET, PATCH/rate-limitLímite de velocidad.
GET, PATCH/bandwidth-limitLímite total de transferencia de datos.
GET/bandwidth-usageUso actual de ancho de banda. Restablece el contador con POST /bandwidth-usage/reset.
GET, PATCH/argumentsArgumentos de línea de comandos personalizados para el túnel.
GET, POST/shared-proxy-clientsLista o añade clientes de un túnel proxy compartido (rotativo). Actualiza o elimina uno con PATCH o DELETE /shared-proxy-clients/{clientId}.
GET/advanced-settingsTodos los ajustes avanzados del túnel en una sola respuesta.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3Lee o cambia un ajuste avanzado.
PATCH/ssl-streamCambia el ajuste de flujo SSL.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessLee o cambia un valor.
GET, PUT/token-groupsLos grupos de tokens asignados al túnel.
GET, PATCH/serverEl servidor del túnel.

AuthTokens #

MétodoRutaFinalidad
GET/auth-tokensLista tus AuthTokens.
GET/auth-tokens/detailLista tus AuthTokens con detalles.
GET/auth-tokens/{token}Detalles de un AuthToken.
POST/auth-tokensCrea un AuthToken.
DELETE/auth-tokens/{token}Elimina un AuthToken.
GET/auth-tokens/{token}/tunnelsLos túneles de un AuthToken.
GET/auth-tokens/{token}/ip-historyHistorial de cambios de la dirección IP pública del dispositivo.
GET, PATCH/auth-tokens/{token}/airplane-mode-settingsAjustes de automatización del modo avión.
POST/auth-tokens/{token}/change-ip-links/{airplaneModeSettingId}Añade un enlace de cambio de IP.
DELETE/auth-tokens/{token}/change-ip-links/{id}Elimina un enlace de cambio de IP.
POST/auth-tokens/{token}/restart-device-links/{airplaneModeSettingId}Añade un enlace de reinicio del dispositivo.
DELETE/auth-tokens/{token}/restart-device-links/{id}Elimina un enlace de reinicio del dispositivo.
GET, PATCH/auth-tokens/{token}/argumentsLos argumentos del cliente guardados en el AuthToken.

Grupos de tokens #

MétodoRutaFinalidad
GET/token-groupsLista tus grupos de tokens.
GET/token-groups/{id}Obtiene un grupo de tokens.
POST/token-groupsCrea un grupo de tokens.
DELETE/token-groups/{id}Elimina un grupo de tokens.
POST/token-groups/{id}/auth-tokensAñade un AuthToken al grupo.
DELETE/token-groups/{id}/auth-tokens/{tokenId}Quita un AuthToken del grupo.

Servidores #

MétodoRutaFinalidad
GET/serversLista los servidores en los que puedes crear túneles, con el serverCode que se usa en las solicitudes de creación.

Proveedores de SSO #

MétodoRutaFinalidad
GET/sso-providersLista tus proveedores de SSO.
GET/sso-providers/default-endpointsEndpoints predeterminados para un tipo de proveedor de SSO.
POST/sso-providersCrea o actualiza un proveedor de SSO.
DELETE/sso-providers/{id}Elimina un proveedor de SSO.
GET/sso-providers/tunnel/{tunnelId}Los proveedores de SSO configurados para un túnel. Aquí tunnelId es el GUID del túnel (guidId).
PUT/sso-providers/tunnel/{tunnelId}Guarda los proveedores de SSO de un túnel.

Consulta Inicio de sesión único para saber qué hacen los proveedores.

Acceso VPN #

El acceso VPN da un perfil de dispositivo WireGuard u OpenVPN en un túnel proxy; todo el tráfico de ese dispositivo sale por el proxy. Estos endpoints empiezan con /tunnels/{tunnelId}/vpn-access.

MétodoRuta después de /tunnels/{tunnelId}/vpn-accessFinalidad
GET(ninguna)Lista los dispositivos VPN del túnel.
POST(ninguna)Crea un dispositivo VPN.
DELETE/{peerId}Elimina (revoca) un dispositivo VPN.
POST/{peerId}/regenerateRegenera las claves de un dispositivo VPN.
GET/{peerId}/configDescarga el archivo de configuración de un dispositivo VPN.
GET/{peerId}/qrCódigo QR de la configuración de un dispositivo WireGuard.
GET/{peerId}/credentialsNombre de usuario y contraseña de un dispositivo OpenVPN.

Solución de problemas #

Todas las solicitudes devuelven 401

Revisa la cabecera: debe ser Authorization: Bearer seguido de un espacio y la clave, sin comillas alrededor de la clave. Si seleccionaste Cambiar en la tarjeta Clave de API, la clave anterior ya no funciona; copia la nueva.

No veo los AuthTokens de mi equipo

Estás usando la clave de API de tu propia cuenta. Cambia al panel del equipo y copia allí la clave de API.

El túnel se creó pero su dirección no responde

Un túnel nuevo está detenido. Llama a POST /tunnels/{tunnelId}/actions/start y comprueba que el cliente de Localtonet del dispositivo se esté ejecutando con el AuthToken que usaste.

Recibo 429 Too Many Requests

Las solicitudes tienen un límite de frecuencia. Espera, vuelve a enviar la solicitud y sustituye los bucles de llamadas individuales por una sola solicitud masiva.

Soporte