Przejdź do treści
Localtonet Localtonet Panel

Ta strona nie jest jeszcze dostępna w języku: Polski. Wyświetlamy ją po angielsku.

Localtonet REST API

Pomoc z tą stroną
Na tej stronie 8 sekcji
  1. Interactive reference
  2. Before you start
  3. Base URL and authentication
  4. Conventions
  5. Errors
  6. Rate limits
  7. Examples
  8. List your tunnels
  9. Create an HTTP tunnel with a random subdomain
  10. Start the tunnel
  11. Endpoint groups
  12. Tunnels
  13. Bulk tunnel operations
  14. Tunnel configuration
  15. AuthTokens
  16. Token groups
  17. Servers
  18. SSO providers
  19. VPN access
  20. Troubleshooting
  21. 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:

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:

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

Send the API key as a Bearer token in the Authorization header of every request:

HTTP
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 #

TopicHow the API behaves
FormatRequest and response bodies are JSON. Send Content-Type: application/json with a body.
Tunnel IDThe 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 codes200 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 endpointsPaths that contain /bulk/ take a JSON array and accept up to 100 items per request (/tunnels/bulk/protocol-type: up to 500).
New tunnelsA 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 #

StatusMeaningBody
400The 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.
401The API key is missing or invalid.No specific message
403, 409Returned 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.
404The tunnel or object was not found or does not belong to you.Empty or a problem object
429Too 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 #

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

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

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
  }'
FieldMeaningValues
authTokenThe AuthToken of the device that runs the tunnel.Required
serverCodeThe server, from GET /servers.Required
protocolTypeThe tunnel type.1 HTTP, 5 File Server, 24 MCP Gateway
ipThe local IP address the tunnel forwards to.A valid IP address, for example 127.0.0.1
portThe local port.1 to 65534
pathThe 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 #

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

MethodPathPurpose
GET/tunnelsList all your tunnels.
GET/tunnels/{tunnelId}Get one tunnel.
POST/tunnels/http/random-subdomainCreate an HTTP, File Server or MCP Gateway tunnel with a random subdomain.
POST/tunnels/http/custom-subdomainCreate one with a subdomain you choose.
POST/tunnels/http/custom-domainCreate one on your own domain.
POST/tunnels/tcp-udpCreate a TCP, UDP or combined TCP and UDP tunnel.
POST/tunnels/proxyCreate an HTTP, SOCKS5, Shadowsocks or VLESS proxy tunnel.
POST/tunnels/proxy/with-detailCreate a proxy tunnel and return its full connection details.
POST/tunnels/shared-proxyCreate a shared (rotating) proxy tunnel.
POST/tunnels/{tunnelId}/actions/startStart a tunnel.
POST/tunnels/{tunnelId}/actions/stopStop a tunnel.
DELETE/tunnels/{tunnelId}Delete a tunnel permanently.
PATCH/tunnels/{tunnelId}/titleChange the title.
PATCH/tunnels/{tunnelId}/local-ipChange the local IP address.
PATCH/tunnels/{tunnelId}/local-portChange the local port.
PATCH/tunnels/{tunnelId}/port-reservedTurn port reservation of a TCP/UDP tunnel on or off.
PATCH/tunnels/{tunnelId}/legacy-connectTurn legacy connection mode on or off.
PATCH/tunnels/{tunnelId}/protocol-typeChange the proxy protocol of a proxy tunnel.
GET/tunnels/{tunnelId}/request-logsRecent HTTP request logs of an HTTP or File Server tunnel.

Bulk tunnel operations #

MethodPathPurpose
POST/tunnels/bulk/http/random-subdomainCreate several HTTP tunnels with random subdomains.
POST/tunnels/bulk/http/custom-subdomainCreate several with custom subdomains.
POST/tunnels/bulk/http/custom-domainCreate several on custom domains.
POST/tunnels/bulk/tcp-udpCreate several TCP/UDP tunnels.
POST/tunnels/bulk/proxyCreate several proxy tunnels.
POST/tunnels/bulk/proxy/with-detailCreate several proxy tunnels and return their connection details.
POST/tunnels/bulk/shared-proxyCreate several shared (rotating) proxy tunnels.
POST/tunnels/bulk/actions/startStart several tunnels. Body: an array of tunnel IDs, for example [123, 456].
POST/tunnels/bulk/actions/stopStop several tunnels. Body: an array of tunnel IDs.
DELETE/tunnels/bulkDelete several tunnels. Body: an array of tunnel IDs.
PATCH/tunnels/bulk/protocol-typeChange 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.

MethodsPath after /tunnels/{tunnelId}Purpose
GET, POST, PATCH, DELETE/ip-restrictionsList, add, set the allow or deny mode, or delete all IP restrictions. Delete one with /ip-restrictions/{restrictionId}.
GET, POST, PATCH, DELETE/access-controlsThe same for URL path access controls. Delete one with /access-controls/{controlId}.
GET, PATCH/headersCustom HTTP headers.
GET, PATCH/authenticationHTTP Basic Authentication.
GET, PATCH/expirationExpiration date of the tunnel.
GET, PATCH/server-portServer-side port of a TCP/UDP tunnel.
GET, PATCH/http-timeoutHTTP request timeout.
GET, PATCH/rate-limitSpeed limit.
GET, PATCH/bandwidth-limitTotal data transfer limit.
GET/bandwidth-usageCurrent bandwidth usage. Reset the counter with POST /bandwidth-usage/reset.
GET, PATCH/argumentsCustom command-line arguments for the tunnel.
GET, POST/shared-proxy-clientsList or add clients of a shared (rotating) proxy tunnel. Update or delete one with PATCH or DELETE /shared-proxy-clients/{clientId}.
GET/advanced-settingsAll advanced settings of the tunnel in one answer.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3Read or switch one advanced setting.
PATCH/ssl-streamSwitch the SSL stream setting.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessRead or change one value.
GET, PUT/token-groupsThe token groups assigned to the tunnel.
GET, PATCH/serverThe server of the tunnel.

AuthTokens #

MethodPathPurpose
GET/auth-tokensList your AuthTokens.
GET/auth-tokens/detailList your AuthTokens with details.
GET/auth-tokens/{token}Details of one AuthToken.
POST/auth-tokensCreate an AuthToken.
DELETE/auth-tokens/{token}Delete an AuthToken.
GET/auth-tokens/{token}/tunnelsThe tunnels of an AuthToken.
GET/auth-tokens/{token}/ip-historyPublic IP address change history of the device.
GET, PATCH/auth-tokens/{token}/airplane-mode-settingsAirplane 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}/argumentsThe client arguments saved on the AuthToken.

Token groups #

MethodPathPurpose
GET/token-groupsList your token groups.
GET/token-groups/{id}Get one token group.
POST/token-groupsCreate a token group.
DELETE/token-groups/{id}Delete a token group.
POST/token-groups/{id}/auth-tokensAdd an AuthToken to the group.
DELETE/token-groups/{id}/auth-tokens/{tokenId}Remove an AuthToken from the group.

Servers #

MethodPathPurpose
GET/serversList the servers you can create tunnels on, with the serverCode to use in create requests.

SSO providers #

MethodPathPurpose
GET/sso-providersList your SSO providers.
GET/sso-providers/default-endpointsDefault endpoints for an SSO provider type.
POST/sso-providersCreate 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.

MethodPath after /tunnels/{tunnelId}/vpn-accessPurpose
GET(none)List the VPN devices of the tunnel.
POST(none)Create a VPN device.
DELETE/{peerId}Delete (revoke) a VPN device.
POST/{peerId}/regenerateRegenerate the keys of a VPN device.
GET/{peerId}/configDownload the configuration file of a VPN device.
GET/{peerId}/qrQR code of a WireGuard device configuration.
GET/{peerId}/credentialsUsername 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.

Pomoc