REST API Localtonet
На этой странице 8 разделов
- Интерактивный справочник
- Перед началом
- Базовый URL и аутентификация
- Соглашения
- Ошибки
- Ограничения частоты запросов
- Примеры
- Список ваших туннелей
- Создание HTTP-туннеля со случайным поддоменом
- Запустите туннель
- Группы конечных точек
- Туннели
- Пакетные операции с туннелями
- Конфигурация туннеля
- AuthToken
- Группы токенов
- Серверы
- SSO-провайдеры
- VPN-доступ
- Устранение неполадок
- Связанные страницы
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 начинаются с:
https://localtonet.com/api/v2Передавайте ключ API как Bearer-токен в заголовке Authorization каждого запроса:
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 устройства.
Список ваших туннелей #
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-туннеля со случайным поддоменом #
Сначала получите код сервера, который хотите использовать:
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"В каждой записи есть serverCode, serverName и serverDomain. Затем создайте туннель. В этом примере трафик перенаправляется на веб-приложение на порту 3000 устройства:
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
}'| Поле | Значение | Значения |
|---|---|---|
authToken | AuthToken устройства, на котором работает туннель. | Обязательно |
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.
Запустите туннель #
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 | /authentication | HTTP 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}/qr | QR-код конфигурации устройства WireGuard. |
| GET | /{peerId}/credentials | Имя пользователя и пароль устройства OpenVPN. |
Устранение неполадок #
Каждый запрос возвращает 401
Проверьте заголовок: он должен иметь вид Authorization: Bearer, затем пробел и ключ, без кавычек вокруг ключа. Если вы нажали Сменить в карточке «Ключ API», старый ключ больше не работает; скопируйте новый.
Я не вижу AuthToken своей команды
Вы используете ключ API своего собственного аккаунта. Переключитесь на командную панель управления и скопируйте ключ API там.
Туннель создан, но его адрес не отвечает
Новый туннель остановлен. Вызовите POST /tunnels/{tunnelId}/actions/start и убедитесь, что клиент Localtonet на устройстве запущен с тем AuthToken, который вы использовали.
Я получаю 429 Too Many Requests
Частота запросов ограничена. Подождите, затем отправьте запрос снова и замените циклы одиночных вызовов одним пакетным запросом.