Перейти к содержимому
Localtonet Localtonet Панель управления

REST API Localtonet

Помощь по этой странице
На этой странице 8 разделов
  1. Интерактивный справочник
  2. Перед началом
  3. Базовый URL и аутентификация
  4. Соглашения
  5. Ошибки
  6. Ограничения частоты запросов
  7. Примеры
  8. Список ваших туннелей
  9. Создание HTTP-туннеля со случайным поддоменом
  10. Запустите туннель
  11. Группы конечных точек
  12. Туннели
  13. Пакетные операции с туннелями
  14. Конфигурация туннеля
  15. AuthToken
  16. Группы токенов
  17. Серверы
  18. SSO-провайдеры
  19. VPN-доступ
  20. Устранение неполадок
  21. Связанные страницы

REST API v2 делает для туннелей то же, что и панель управления: создаёт, запускает, останавливает, удаляет и настраивает их, а также управляет AuthToken, группами токенов и SSO-провайдерами. Каждый запрос вы аутентифицируете своим ключом API.

Интерактивный справочник #

Все конечные точки с моделями запросов и ответов и формой для пробного вызова собраны в интерактивном справочнике:

  • localtonet.com/api: API v2, актуальная версия. Туда же ведёт кнопка API UI на панели управления.
  • localtonet.com/api/v1: API v1, сохранён для существующих интеграций. Для новых задач используйте v2.

Эта страница описывает общие соглашения и даёт обзор групп конечных точек. Точные поля запроса смотрите в описании конкретной конечной точки в справочнике.

Перед началом #

  • Ваш ключ API. Откройте Панель управления и нажмите Копировать в карточке Ключ API. См. Аккаунт и безопасность.
  • Для создания туннеля: AuthToken устройства, на котором будет работать туннель, и клиент Localtonet, подключённый с этим токеном. См. AuthToken.

Храните ключ API в тайне. Любой, у кого он есть, может создавать, изменять и удалять ваши туннели и токены. Кнопка Сменить в карточке «Ключ API» создаёт новый ключ и аннулирует старый.

Базовый URL и аутентификация #

Все конечные точки v2 начинаются с:

Базовый URL
https://localtonet.com/api/v2

Передавайте ключ API как Bearer-токен в заголовке Authorization каждого запроса:

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

Ключ API, скопированный в командной панели управления, показывает ваши AuthToken и туннели в этой команде; ключ вашего собственного аккаунта показывает AuthToken, не относящиеся ни к одной команде.

Соглашения #

ТемаКак ведёт себя API
ФорматТела запросов и ответов — JSON. Если запрос содержит тело, передавайте Content-Type: application/json.
ID туннеляtunnelId в пути — это числовой id туннеля, который возвращают конечные точки списка и создания.
AuthToken в пути{token} — это сама строка AuthToken.
Коды успеха200 с телом для чтения, 201 для большинства операций создания (конечные точки создания туннелей возвращают новый туннель), 204 без тела для большинства действий и обновлений. Ответ каждой конечной точки показан в справочнике.
Пакетные конечные точкиПути, содержащие /bulk/, принимают JSON-массив и допускают до 100 элементов в запросе (/tunnels/bulk/protocol-type: до 500).
Новые туннелиСозданный туннель ещё не запущен. Запустите его действием start. Только конечные точки proxy/with-detail могут запустить туннель в том же вызове с помощью isStartAfterCreate.

Ошибки #

СтатусЗначениеТело
400Тело запроса некорректно, или операция отклонена, например из-за ограничения вашего тарифа.Для большинства конечных точек — JSON-объект problem; сообщение находится в title. Ошибки валидации и ошибки пакетных конечных точек перечислены в errors.
401Ключ API отсутствует или недействителен.Без специального сообщения
403, 409Возвращается некоторыми конечными точками настройки туннеля и VPN-доступа, когда изменение не разрешено или конфликтует с текущей конфигурацией.Объект problem с сообщением в title.
404Туннель или объект не найден либо не принадлежит вам.Пустое тело или объект problem
429Слишком много запросов.См. ниже раздел «Ограничения частоты запросов».

Ограничения частоты запросов #

Частота запросов ограничена. На запрос сверх лимита сервер отвечает 429 Too Many Requests. Подождите и отправьте его снова; вместо множества одиночных вызовов используйте пакетные конечные точки.

Примеры #

Замените <YOUR_API_KEY> своим ключом API, а <YOUR_TOKEN> — AuthToken устройства.

Список ваших туннелей #

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

Ответ — JSON-массив с одним объектом на каждый туннель. Среди его полей: id, title, url (публичный адрес), protocolType, authToken, serverId, clientIp и clientPort (локальная цель), status и connectionStatus. Если у вас ещё нет туннелей, ответом будет 404, а не пустой массив.

Создание HTTP-туннеля со случайным поддоменом #

Сначала получите код сервера, который хотите использовать:

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

В каждой записи есть serverCode, serverName и serverDomain. Затем создайте туннель. В этом примере трафик перенаправляется на веб-приложение на порту 3000 устройства:

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
  }'
ПолеЗначениеЗначения
authTokenAuthToken устройства, на котором работает туннель.Обязательно
serverCodeСервер, из GET /servers.Обязательно
protocolTypeТип туннеля.1 HTTP, 5 File Server, 24 MCP Gateway
ipЛокальный IP-адрес, на который туннель перенаправляет трафик.Корректный IP-адрес, например 127.0.0.1
portЛокальный порт.От 1 до 65534
pathЛокальная папка, к которой открывается доступ.Обязательно только для File Server

Ответ — 201 Created с новым туннелем. Запомните его id и url.

Запустите туннель #

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

Ответ — 204 No Content. Туннель становится доступен по своему url, когда клиент устройства подключён. Остановить его снова можно через /actions/stop.

Группы конечных точек #

Все пути ниже указаны относительно https://localtonet.com/api/v2.

Туннели #

МетодПутьНазначение
GET/tunnelsСписок всех ваших туннелей.
GET/tunnels/{tunnelId}Получение одного туннеля.
POST/tunnels/http/random-subdomainСоздание туннеля HTTP, File Server или MCP Gateway со случайным поддоменом.
POST/tunnels/http/custom-subdomainСоздание туннеля с выбранным вами поддоменом.
POST/tunnels/http/custom-domainСоздание туннеля на вашем собственном домене.
POST/tunnels/tcp-udpСоздание туннеля TCP, UDP или комбинированного TCP и UDP.
POST/tunnels/proxyСоздание прокси-туннеля HTTP, SOCKS5, Shadowsocks или VLESS.
POST/tunnels/proxy/with-detailСоздание прокси-туннеля с возвратом полных данных для подключения.
POST/tunnels/shared-proxyСоздание общего (ротационного) прокси-туннеля.
POST/tunnels/{tunnelId}/actions/startЗапуск туннеля.
POST/tunnels/{tunnelId}/actions/stopОстановка туннеля.
DELETE/tunnels/{tunnelId}Безвозвратное удаление туннеля.
PATCH/tunnels/{tunnelId}/titleИзменение названия.
PATCH/tunnels/{tunnelId}/local-ipИзменение локального IP-адреса.
PATCH/tunnels/{tunnelId}/local-portИзменение локального порта.
PATCH/tunnels/{tunnelId}/port-reservedВключение и выключение резервирования порта туннеля TCP/UDP.
PATCH/tunnels/{tunnelId}/legacy-connectВключение и выключение устаревшего режима подключения.
PATCH/tunnels/{tunnelId}/protocol-typeИзменение протокола прокси у прокси-туннеля.
GET/tunnels/{tunnelId}/request-logsПоследние журналы HTTP-запросов туннеля HTTP или File Server.

Пакетные операции с туннелями #

МетодПутьНазначение
POST/tunnels/bulk/http/random-subdomainСоздание нескольких HTTP-туннелей со случайными поддоменами.
POST/tunnels/bulk/http/custom-subdomainСоздание нескольких туннелей с пользовательскими поддоменами.
POST/tunnels/bulk/http/custom-domainСоздание нескольких туннелей на пользовательских доменах.
POST/tunnels/bulk/tcp-udpСоздание нескольких туннелей TCP/UDP.
POST/tunnels/bulk/proxyСоздание нескольких прокси-туннелей.
POST/tunnels/bulk/proxy/with-detailСоздание нескольких прокси-туннелей с возвратом данных для подключения.
POST/tunnels/bulk/shared-proxyСоздание нескольких общих (ротационных) прокси-туннелей.
POST/tunnels/bulk/actions/startЗапуск нескольких туннелей. Тело: массив ID туннелей, например [123, 456].
POST/tunnels/bulk/actions/stopОстановка нескольких туннелей. Тело: массив ID туннелей.
DELETE/tunnels/bulkУдаление нескольких туннелей. Тело: массив ID туннелей.
PATCH/tunnels/bulk/protocol-typeИзменение протокола прокси у нескольких прокси-туннелей.

Конфигурация туннеля #

Эти конечные точки меняют настройки одного туннеля. Все они начинаются с /tunnels/{tunnelId}. Что делает каждая настройка, описано в справочнике по настройкам.

МетодыПуть после /tunnels/{tunnelId}Назначение
GET, POST, PATCH, DELETE/ip-restrictionsПросмотр, добавление, выбор режима «разрешить» или «запретить» и удаление всех ограничений по IP. Удалить одно ограничение можно через /ip-restrictions/{restrictionId}.
GET, POST, PATCH, DELETE/access-controlsТо же для правил доступа по пути URL. Удалить одно правило можно через /access-controls/{controlId}.
GET, PATCH/headersПользовательские HTTP-заголовки.
GET, PATCH/authenticationHTTP Basic Authentication.
GET, PATCH/expirationДата окончания срока действия туннеля.
GET, PATCH/server-portСерверный порт туннеля TCP/UDP.
GET, PATCH/http-timeoutТайм-аут HTTP-запроса.
GET, PATCH/rate-limitОграничение скорости.
GET, PATCH/bandwidth-limitОграничение общего объёма передачи данных.
GET/bandwidth-usageТекущее использование трафика. Сбросить счётчик можно через POST /bandwidth-usage/reset.
GET, PATCH/argumentsПользовательские аргументы командной строки для туннеля.
GET, POST/shared-proxy-clientsПросмотр и добавление клиентов общего (ротационного) прокси-туннеля. Изменить или удалить клиента можно через PATCH или DELETE /shared-proxy-clients/{clientId}.
GET/advanced-settingsВсе расширенные настройки туннеля в одном ответе.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3Чтение или переключение одной расширенной настройки.
PATCH/ssl-streamПереключение настройки SSL-потока.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessЧтение или изменение одного значения.
GET, PUT/token-groupsГруппы токенов, назначенные туннелю.
GET, PATCH/serverСервер туннеля.

AuthToken #

МетодПутьНазначение
GET/auth-tokensСписок ваших AuthToken.
GET/auth-tokens/detailСписок ваших AuthToken с подробностями.
GET/auth-tokens/{token}Подробности об одном AuthToken.
POST/auth-tokensСоздание AuthToken.
DELETE/auth-tokens/{token}Удаление AuthToken.
GET/auth-tokens/{token}/tunnelsТуннели AuthToken.
GET/auth-tokens/{token}/ip-historyИстория смены публичного IP-адреса устройства.
GET, PATCH/auth-tokens/{token}/airplane-mode-settingsНастройки автоматизации режима «в самолёте».
POST/auth-tokens/{token}/change-ip-links/{airplaneModeSettingId}Добавление ссылки для смены IP.
DELETE/auth-tokens/{token}/change-ip-links/{id}Удаление ссылки для смены IP.
POST/auth-tokens/{token}/restart-device-links/{airplaneModeSettingId}Добавление ссылки для перезагрузки устройства.
DELETE/auth-tokens/{token}/restart-device-links/{id}Удаление ссылки для перезагрузки устройства.
GET, PATCH/auth-tokens/{token}/argumentsАргументы клиента, сохранённые в AuthToken.

Группы токенов #

МетодПутьНазначение
GET/token-groupsСписок ваших групп токенов.
GET/token-groups/{id}Получение одной группы токенов.
POST/token-groupsСоздание группы токенов.
DELETE/token-groups/{id}Удаление группы токенов.
POST/token-groups/{id}/auth-tokensДобавление AuthToken в группу.
DELETE/token-groups/{id}/auth-tokens/{tokenId}Удаление AuthToken из группы.

Серверы #

МетодПутьНазначение
GET/serversСписок серверов, на которых вы можете создавать туннели, с serverCode, который нужно указывать в запросах на создание.

SSO-провайдеры #

МетодПутьНазначение
GET/sso-providersСписок ваших SSO-провайдеров.
GET/sso-providers/default-endpointsКонечные точки по умолчанию для типа SSO-провайдера.
POST/sso-providersСоздание или обновление SSO-провайдера.
DELETE/sso-providers/{id}Удаление SSO-провайдера.
GET/sso-providers/tunnel/{tunnelId}SSO-провайдеры, настроенные для туннеля. Здесь tunnelId — это GUID туннеля (guidId).
PUT/sso-providers/tunnel/{tunnelId}Сохранение SSO-провайдеров туннеля.

О назначении провайдеров см. Единый вход.

VPN-доступ #

VPN-доступ выдаёт профиль устройства WireGuard или OpenVPN для прокси-туннеля; весь трафик этого устройства выходит через прокси. Эти конечные точки начинаются с /tunnels/{tunnelId}/vpn-access.

МетодПуть после /tunnels/{tunnelId}/vpn-accessНазначение
GET(нет)Список VPN-устройств туннеля.
POST(нет)Создание VPN-устройства.
DELETE/{peerId}Удаление (отзыв) VPN-устройства.
POST/{peerId}/regenerateПовторная генерация ключей VPN-устройства.
GET/{peerId}/configСкачивание файла конфигурации VPN-устройства.
GET/{peerId}/qrQR-код конфигурации устройства WireGuard.
GET/{peerId}/credentialsИмя пользователя и пароль устройства OpenVPN.

Устранение неполадок #

Каждый запрос возвращает 401

Проверьте заголовок: он должен иметь вид Authorization: Bearer, затем пробел и ключ, без кавычек вокруг ключа. Если вы нажали Сменить в карточке «Ключ API», старый ключ больше не работает; скопируйте новый.

Я не вижу AuthToken своей команды

Вы используете ключ API своего собственного аккаунта. Переключитесь на командную панель управления и скопируйте ключ API там.

Туннель создан, но его адрес не отвечает

Новый туннель остановлен. Вызовите POST /tunnels/{tunnelId}/actions/start и убедитесь, что клиент Localtonet на устройстве запущен с тем AuthToken, который вы использовали.

Я получаю 429 Too Many Requests

Частота запросов ограничена. Подождите, затем отправьте запрос снова и замените циклы одиночных вызовов одним пакетным запросом.

Поддержка