API REST de Localtonet
En esta página 8 secciones
- Referencia interactiva
- Antes de empezar
- URL base y autenticación
- Convenciones
- Errores
- Límites de frecuencia
- Ejemplos
- Lista tus túneles
- Crea un túnel HTTP con un subdominio aleatorio
- Inicia el túnel
- Grupos de endpoints
- Túneles
- Operaciones masivas con túneles
- Configuración del túnel
- AuthTokens
- Grupos de tokens
- Servidores
- Proveedores de SSO
- Acceso VPN
- Solución de problemas
- 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:
https://localtonet.com/api/v2Envía la clave de API como token Bearer en la cabecera Authorization de cada solicitud:
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 #
| Tema | Cómo se comporta la API |
|---|---|
| Formato | Los cuerpos de solicitud y de respuesta son JSON. Envía Content-Type: application/json cuando haya cuerpo. |
| ID del túnel | El 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 éxito | 200 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 masivos | Las rutas que contienen /bulk/ aceptan un array JSON con hasta 100 elementos por solicitud (/tunnels/bulk/protocol-type: hasta 500). |
| Túneles nuevos | Un 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 #
| Estado | Significado | Cuerpo |
|---|---|---|
400 | El 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. |
401 | Falta la clave de API o no es válida. | Sin mensaje específico |
403, 409 | Lo 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. |
404 | No se encontró el túnel o el objeto, o no te pertenece. | Vacío o un objeto de problema |
429 | Demasiadas 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 #
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:
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:
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 | El AuthToken del dispositivo que ejecuta el túnel. | Obligatorio |
serverCode | El servidor, de GET /servers. | Obligatorio |
protocolType | El tipo de túnel. | 1 HTTP, 5 File Server, 24 MCP Gateway |
ip | La dirección IP local a la que reenvía el túnel. | Una dirección IP válida, por ejemplo 127.0.0.1 |
port | El puerto local. | De 1 a 65534 |
path | La 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 #
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étodo | Ruta | Finalidad |
|---|---|---|
| GET | /tunnels | Lista todos tus túneles. |
| GET | /tunnels/{tunnelId} | Obtiene un túnel. |
| POST | /tunnels/http/random-subdomain | Crea un túnel HTTP, File Server o MCP Gateway con un subdominio aleatorio. |
| POST | /tunnels/http/custom-subdomain | Crea uno con un subdominio que eliges. |
| POST | /tunnels/http/custom-domain | Crea uno en tu propio dominio. |
| POST | /tunnels/tcp-udp | Crea un túnel TCP, UDP o combinado TCP y UDP. |
| POST | /tunnels/proxy | Crea un túnel proxy HTTP, SOCKS5, Shadowsocks o VLESS. |
| POST | /tunnels/proxy/with-detail | Crea un túnel proxy y devuelve sus datos de conexión completos. |
| POST | /tunnels/shared-proxy | Crea un túnel proxy compartido (rotativo). |
| POST | /tunnels/{tunnelId}/actions/start | Inicia un túnel. |
| POST | /tunnels/{tunnelId}/actions/stop | Detiene un túnel. |
| DELETE | /tunnels/{tunnelId} | Elimina un túnel de forma permanente. |
| PATCH | /tunnels/{tunnelId}/title | Cambia el título. |
| PATCH | /tunnels/{tunnelId}/local-ip | Cambia la dirección IP local. |
| PATCH | /tunnels/{tunnelId}/local-port | Cambia el puerto local. |
| PATCH | /tunnels/{tunnelId}/port-reserved | Activa o desactiva la reserva de puerto de un túnel TCP/UDP. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | Activa o desactiva el modo de conexión heredado. |
| PATCH | /tunnels/{tunnelId}/protocol-type | Cambia el protocolo proxy de un túnel proxy. |
| GET | /tunnels/{tunnelId}/request-logs | Registros de las solicitudes HTTP recientes de un túnel HTTP o File Server. |
Operaciones masivas con túneles #
| Método | Ruta | Finalidad |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | Crea varios túneles HTTP con subdominios aleatorios. |
| POST | /tunnels/bulk/http/custom-subdomain | Crea varios con subdominios personalizados. |
| POST | /tunnels/bulk/http/custom-domain | Crea varios en dominios personalizados. |
| POST | /tunnels/bulk/tcp-udp | Crea varios túneles TCP/UDP. |
| POST | /tunnels/bulk/proxy | Crea varios túneles proxy. |
| POST | /tunnels/bulk/proxy/with-detail | Crea varios túneles proxy y devuelve sus datos de conexión. |
| POST | /tunnels/bulk/shared-proxy | Crea varios túneles proxy compartidos (rotativos). |
| POST | /tunnels/bulk/actions/start | Inicia varios túneles. Cuerpo: un array de ID de túneles, por ejemplo [123, 456]. |
| POST | /tunnels/bulk/actions/stop | Detiene varios túneles. Cuerpo: un array de ID de túneles. |
| DELETE | /tunnels/bulk | Elimina varios túneles. Cuerpo: un array de ID de túneles. |
| PATCH | /tunnels/bulk/protocol-type | Cambia 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étodos | Ruta después de /tunnels/{tunnelId} | Finalidad |
|---|---|---|
| GET, POST, PATCH, DELETE | /ip-restrictions | Lista, 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-controls | Lo mismo para los controles de acceso por ruta URL. Elimina uno con /access-controls/{controlId}. |
| GET, PATCH | /headers | Cabeceras HTTP personalizadas. |
| GET, PATCH | /authentication | Autenticación básica HTTP. |
| GET, PATCH | /expiration | Fecha de caducidad del túnel. |
| GET, PATCH | /server-port | Puerto del lado del servidor de un túnel TCP/UDP. |
| GET, PATCH | /http-timeout | Tiempo de espera de las solicitudes HTTP. |
| GET, PATCH | /rate-limit | Límite de velocidad. |
| GET, PATCH | /bandwidth-limit | Límite total de transferencia de datos. |
| GET | /bandwidth-usage | Uso actual de ancho de banda. Restablece el contador con POST /bandwidth-usage/reset. |
| GET, PATCH | /arguments | Argumentos de línea de comandos personalizados para el túnel. |
| GET, POST | /shared-proxy-clients | Lista 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-settings | Todos los ajustes avanzados del túnel en una sola respuesta. |
| GET, PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | Lee o cambia un ajuste avanzado. |
| PATCH | /ssl-stream | Cambia el ajuste de flujo SSL. |
| GET, PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | Lee o cambia un valor. |
| GET, PUT | /token-groups | Los grupos de tokens asignados al túnel. |
| GET, PATCH | /server | El servidor del túnel. |
AuthTokens #
| Método | Ruta | Finalidad |
|---|---|---|
| GET | /auth-tokens | Lista tus AuthTokens. |
| GET | /auth-tokens/detail | Lista tus AuthTokens con detalles. |
| GET | /auth-tokens/{token} | Detalles de un AuthToken. |
| POST | /auth-tokens | Crea un AuthToken. |
| DELETE | /auth-tokens/{token} | Elimina un AuthToken. |
| GET | /auth-tokens/{token}/tunnels | Los túneles de un AuthToken. |
| GET | /auth-tokens/{token}/ip-history | Historial de cambios de la dirección IP pública del dispositivo. |
| GET, PATCH | /auth-tokens/{token}/airplane-mode-settings | Ajustes 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}/arguments | Los argumentos del cliente guardados en el AuthToken. |
Grupos de tokens #
| Método | Ruta | Finalidad |
|---|---|---|
| GET | /token-groups | Lista tus grupos de tokens. |
| GET | /token-groups/{id} | Obtiene un grupo de tokens. |
| POST | /token-groups | Crea un grupo de tokens. |
| DELETE | /token-groups/{id} | Elimina un grupo de tokens. |
| POST | /token-groups/{id}/auth-tokens | Añade un AuthToken al grupo. |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | Quita un AuthToken del grupo. |
Servidores #
| Método | Ruta | Finalidad |
|---|---|---|
| GET | /servers | Lista 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étodo | Ruta | Finalidad |
|---|---|---|
| GET | /sso-providers | Lista tus proveedores de SSO. |
| GET | /sso-providers/default-endpoints | Endpoints predeterminados para un tipo de proveedor de SSO. |
| POST | /sso-providers | Crea 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étodo | Ruta después de /tunnels/{tunnelId}/vpn-access | Finalidad |
|---|---|---|
| GET | (ninguna) | Lista los dispositivos VPN del túnel. |
| POST | (ninguna) | Crea un dispositivo VPN. |
| DELETE | /{peerId} | Elimina (revoca) un dispositivo VPN. |
| POST | /{peerId}/regenerate | Regenera las claves de un dispositivo VPN. |
| GET | /{peerId}/config | Descarga el archivo de configuración de un dispositivo VPN. |
| GET | /{peerId}/qr | Código QR de la configuración de un dispositivo WireGuard. |
| GET | /{peerId}/credentials | Nombre 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.