Trang này chưa có bản Tiếng Việt. Đang hiển thị bằng tiếng Anh.
Localtonet REST API
Trong trang này 8 mục
- Interactive reference
- Before you start
- Base URL and authentication
- Conventions
- Errors
- Rate limits
- Examples
- List your tunnels
- Create an HTTP tunnel with a random subdomain
- Start the tunnel
- Endpoint groups
- Tunnels
- Bulk tunnel operations
- Tunnel configuration
- AuthTokens
- Token groups
- Servers
- SSO providers
- VPN access
- Troubleshooting
- Related pages
The REST API v2 does what the dashboard does for tunnels: create, start, stop, delete and configure them, and manage AuthTokens, token groups and SSO providers. You authenticate every request with your API key.
Interactive reference #
Every endpoint, with its request and response models and a form to try it, is in the interactive reference:
- localtonet.com/api: API v2, the current version. You also reach it with the API UI button on the dashboard.
- localtonet.com/api/v1: API v1, kept for existing integrations. Use v2 for new work.
This page gives you the conventions and an overview of the endpoint groups. For the exact fields of a request, open the endpoint in the reference.
Before you start #
- Your API key. Open the Dashboard and use Copy in the API Key card. See Account and security.
- For tunnel creation: an AuthToken of the device that will run the tunnel, and a Localtonet client connected with that token. See AuthTokens.
Keep your API key private. Anyone who has it can create, change and delete your tunnels and tokens. Change in the API Key card creates a new key and invalidates the old one.
Base URL and authentication #
All v2 endpoints start with:
https://localtonet.com/api/v2Send the API key as a Bearer token in the Authorization header of every request:
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>An API key copied in a team dashboard lists your AuthTokens and tunnels in that team; the key of your own account lists the AuthTokens that belong to no team.
Conventions #
| Topic | How the API behaves |
|---|---|
| Format | Request and response bodies are JSON. Send Content-Type: application/json with a body. |
| Tunnel ID | The tunnelId in a path is the numeric id of the tunnel, as returned by the list and create endpoints. |
| AuthToken in a path | {token} is the AuthToken string itself. |
| Success codes | 200 with a body for reads, 201 for most creates (the tunnel create endpoints return the new tunnel), 204 without a body for most actions and updates. The reference shows the answer of each endpoint. |
| Bulk endpoints | Paths that contain /bulk/ take a JSON array and accept up to 100 items per request (/tunnels/bulk/protocol-type: up to 500). |
| New tunnels | A tunnel you create is not running yet. Start it with the start action. Only the proxy/with-detail endpoints can start the tunnel in the same call, with isStartAfterCreate. |
Errors #
| Status | Meaning | Body |
|---|---|---|
400 | The request body is not valid, or the operation was refused, for example because of a limit of your plan. | For most endpoints a problem object in JSON; title holds the message. Validation errors and the errors of bulk endpoints are listed under errors. |
401 | The API key is missing or invalid. | No specific message |
403, 409 | Returned by some tunnel configuration and VPN access endpoints when the change is not permitted or conflicts with the current configuration. | A problem object with the message in title. |
404 | The tunnel or object was not found or does not belong to you. | Empty or a problem object |
429 | Too many requests. | See rate limits below. |
Rate limits #
Requests are rate limited. A request over the limit is answered with 429 Too Many Requests. Wait and send it again; use the bulk endpoints instead of many single calls.
Examples #
Replace <YOUR_API_KEY> with your API key and <YOUR_TOKEN> with the AuthToken of the device.
List your tunnels #
curl https://localtonet.com/api/v2/tunnels \
-H "Authorization: Bearer <YOUR_API_KEY>"The answer is a JSON array with one object per tunnel. Among its fields are id, title, url (the public address), protocolType, authToken, serverId, clientIp and clientPort (the local target), status and connectionStatus. If you have no tunnels yet, the answer is 404 instead of an empty array.
Create an HTTP tunnel with a random subdomain #
First get the code of the server you want to use:
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"Each entry has a serverCode, a serverName and a serverDomain. Then create the tunnel. This example forwards to a web app on port 3000 of the device:
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
}'| Field | Meaning | Values |
|---|---|---|
authToken | The AuthToken of the device that runs the tunnel. | Required |
serverCode | The server, from GET /servers. | Required |
protocolType | The tunnel type. | 1 HTTP, 5 File Server, 24 MCP Gateway |
ip | The local IP address the tunnel forwards to. | A valid IP address, for example 127.0.0.1 |
port | The local port. | 1 to 65534 |
path | The local folder to share. | Required for File Server only |
The answer is 201 Created with the new tunnel. Note its id and url.
Start the tunnel #
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
-H "Authorization: Bearer <YOUR_API_KEY>"The answer is 204 No Content. The tunnel becomes reachable at its url when the client of the device is connected. Stop it again with /actions/stop.
Endpoint groups #
All paths below are relative to https://localtonet.com/api/v2.
Tunnels #
| Method | Path | Purpose |
|---|---|---|
| GET | /tunnels | List all your tunnels. |
| GET | /tunnels/{tunnelId} | Get one tunnel. |
| POST | /tunnels/http/random-subdomain | Create an HTTP, File Server or MCP Gateway tunnel with a random subdomain. |
| POST | /tunnels/http/custom-subdomain | Create one with a subdomain you choose. |
| POST | /tunnels/http/custom-domain | Create one on your own domain. |
| POST | /tunnels/tcp-udp | Create a TCP, UDP or combined TCP and UDP tunnel. |
| POST | /tunnels/proxy | Create an HTTP, SOCKS5, Shadowsocks or VLESS proxy tunnel. |
| POST | /tunnels/proxy/with-detail | Create a proxy tunnel and return its full connection details. |
| POST | /tunnels/shared-proxy | Create a shared (rotating) proxy tunnel. |
| POST | /tunnels/{tunnelId}/actions/start | Start a tunnel. |
| POST | /tunnels/{tunnelId}/actions/stop | Stop a tunnel. |
| DELETE | /tunnels/{tunnelId} | Delete a tunnel permanently. |
| PATCH | /tunnels/{tunnelId}/title | Change the title. |
| PATCH | /tunnels/{tunnelId}/local-ip | Change the local IP address. |
| PATCH | /tunnels/{tunnelId}/local-port | Change the local port. |
| PATCH | /tunnels/{tunnelId}/port-reserved | Turn port reservation of a TCP/UDP tunnel on or off. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | Turn legacy connection mode on or off. |
| PATCH | /tunnels/{tunnelId}/protocol-type | Change the proxy protocol of a proxy tunnel. |
| GET | /tunnels/{tunnelId}/request-logs | Recent HTTP request logs of an HTTP or File Server tunnel. |
Bulk tunnel operations #
| Method | Path | Purpose |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | Create several HTTP tunnels with random subdomains. |
| POST | /tunnels/bulk/http/custom-subdomain | Create several with custom subdomains. |
| POST | /tunnels/bulk/http/custom-domain | Create several on custom domains. |
| POST | /tunnels/bulk/tcp-udp | Create several TCP/UDP tunnels. |
| POST | /tunnels/bulk/proxy | Create several proxy tunnels. |
| POST | /tunnels/bulk/proxy/with-detail | Create several proxy tunnels and return their connection details. |
| POST | /tunnels/bulk/shared-proxy | Create several shared (rotating) proxy tunnels. |
| POST | /tunnels/bulk/actions/start | Start several tunnels. Body: an array of tunnel IDs, for example [123, 456]. |
| POST | /tunnels/bulk/actions/stop | Stop several tunnels. Body: an array of tunnel IDs. |
| DELETE | /tunnels/bulk | Delete several tunnels. Body: an array of tunnel IDs. |
| PATCH | /tunnels/bulk/protocol-type | Change the proxy protocol of several proxy tunnels. |
Tunnel configuration #
These endpoints change the settings of one tunnel. They all start with /tunnels/{tunnelId}. What each setting does is described in the Settings reference.
| Methods | Path after /tunnels/{tunnelId} | Purpose |
|---|---|---|
| GET, POST, PATCH, DELETE | /ip-restrictions | List, add, set the allow or deny mode, or delete all IP restrictions. Delete one with /ip-restrictions/{restrictionId}. |
| GET, POST, PATCH, DELETE | /access-controls | The same for URL path access controls. Delete one with /access-controls/{controlId}. |
| GET, PATCH | /headers | Custom HTTP headers. |
| GET, PATCH | /authentication | HTTP Basic Authentication. |
| GET, PATCH | /expiration | Expiration date of the tunnel. |
| GET, PATCH | /server-port | Server-side port of a TCP/UDP tunnel. |
| GET, PATCH | /http-timeout | HTTP request timeout. |
| GET, PATCH | /rate-limit | Speed limit. |
| GET, PATCH | /bandwidth-limit | Total data transfer limit. |
| GET | /bandwidth-usage | Current bandwidth usage. Reset the counter with POST /bandwidth-usage/reset. |
| GET, PATCH | /arguments | Custom command-line arguments for the tunnel. |
| GET, POST | /shared-proxy-clients | List or add clients of a shared (rotating) proxy tunnel. Update or delete one with PATCH or DELETE /shared-proxy-clients/{clientId}. |
| GET | /advanced-settings | All advanced settings of the tunnel in one answer. |
| GET, PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | Read or switch one advanced setting. |
| PATCH | /ssl-stream | Switch the SSL stream setting. |
| GET, PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | Read or change one value. |
| GET, PUT | /token-groups | The token groups assigned to the tunnel. |
| GET, PATCH | /server | The server of the tunnel. |
AuthTokens #
| Method | Path | Purpose |
|---|---|---|
| GET | /auth-tokens | List your AuthTokens. |
| GET | /auth-tokens/detail | List your AuthTokens with details. |
| GET | /auth-tokens/{token} | Details of one AuthToken. |
| POST | /auth-tokens | Create an AuthToken. |
| DELETE | /auth-tokens/{token} | Delete an AuthToken. |
| GET | /auth-tokens/{token}/tunnels | The tunnels of an AuthToken. |
| GET | /auth-tokens/{token}/ip-history | Public IP address change history of the device. |
| GET, PATCH | /auth-tokens/{token}/airplane-mode-settings | Airplane mode automation settings. |
| POST | /auth-tokens/{token}/change-ip-links/{airplaneModeSettingId} | Add a change-IP link. |
| DELETE | /auth-tokens/{token}/change-ip-links/{id} | Delete a change-IP link. |
| POST | /auth-tokens/{token}/restart-device-links/{airplaneModeSettingId} | Add a restart-device link. |
| DELETE | /auth-tokens/{token}/restart-device-links/{id} | Delete a restart-device link. |
| GET, PATCH | /auth-tokens/{token}/arguments | The client arguments saved on the AuthToken. |
Token groups #
| Method | Path | Purpose |
|---|---|---|
| GET | /token-groups | List your token groups. |
| GET | /token-groups/{id} | Get one token group. |
| POST | /token-groups | Create a token group. |
| DELETE | /token-groups/{id} | Delete a token group. |
| POST | /token-groups/{id}/auth-tokens | Add an AuthToken to the group. |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | Remove an AuthToken from the group. |
Servers #
| Method | Path | Purpose |
|---|---|---|
| GET | /servers | List the servers you can create tunnels on, with the serverCode to use in create requests. |
SSO providers #
| Method | Path | Purpose |
|---|---|---|
| GET | /sso-providers | List your SSO providers. |
| GET | /sso-providers/default-endpoints | Default endpoints for an SSO provider type. |
| POST | /sso-providers | Create or update an SSO provider. |
| DELETE | /sso-providers/{id} | Delete an SSO provider. |
| GET | /sso-providers/tunnel/{tunnelId} | The SSO providers configured for a tunnel. Here tunnelId is the GUID of the tunnel (guidId). |
| PUT | /sso-providers/tunnel/{tunnelId} | Save the SSO providers of a tunnel. |
See Single Sign-On for what the providers do.
VPN access #
VPN access gives a WireGuard or OpenVPN device profile on a proxy tunnel; the whole traffic of that device leaves through the proxy. These endpoints start with /tunnels/{tunnelId}/vpn-access.
| Method | Path after /tunnels/{tunnelId}/vpn-access | Purpose |
|---|---|---|
| GET | (none) | List the VPN devices of the tunnel. |
| POST | (none) | Create a VPN device. |
| DELETE | /{peerId} | Delete (revoke) a VPN device. |
| POST | /{peerId}/regenerate | Regenerate the keys of a VPN device. |
| GET | /{peerId}/config | Download the configuration file of a VPN device. |
| GET | /{peerId}/qr | QR code of a WireGuard device configuration. |
| GET | /{peerId}/credentials | Username and password of an OpenVPN device. |
Troubleshooting #
Every request returns 401
Check the header: it must be Authorization: Bearer followed by a space and the key, with no quotes around the key. If you selected Change in the API Key card, the old key no longer works; copy the new one.
I do not see my team's AuthTokens
You are using the API key of your own account. Switch to the team dashboard and copy the API key there.
The tunnel was created but its address does not answer
A new tunnel is stopped. Call POST /tunnels/{tunnelId}/actions/start, and check that the Localtonet client of the device is running with the AuthToken you used.
I get 429 Too Many Requests
Requests are rate limited. Wait, then send the request again, and replace loops of single calls with one bulk request.