Перейти до вмісту
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).
Нові тунеліСтворений вами тунель ще не працює. Запустіть його дією запуску. Лише кінцеві точки proxy/with-detail можуть запустити тунель тим самим викликом за допомогою isStartAfterCreate.

Помилки #

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

Обмеження частоти запитів #

Частота запитів обмежена. На запит понад ліміт API відповідає 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/authenticationБазова автентифікація HTTP.
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

Частота запитів обмежена. Зачекайте, потім надішліть запит знову, а цикли окремих викликів замініть одним пакетним запитом.

Підтримка