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). |
| Нові тунелі | Створений вами тунель ще не працює. Запустіть його дією запуску. Лише кінцеві точки proxy/with-detail можуть запустити тунель тим самим викликом за допомогою isStartAfterCreate. |
Помилки #
| Статус | Значення | Тіло |
|---|---|---|
400 | Тіло запиту недійсне, або операцію відхилено, наприклад через ліміт вашого тарифу. | Для більшості кінцевих точок — об’єкт problem у форматі JSON; повідомлення міститься в title. Помилки перевірки та помилки пакетних кінцевих точок перелічено в errors. |
401 | API-ключ відсутній або недійсний. | Без окремого повідомлення |
403, 409 | Повертається деякими кінцевими точками налаштування тунелю та доступу VPN, коли зміна не дозволена або суперечить поточній конфігурації. | Об’єкт problem із повідомленням у title. |
404 | Тунель або об’єкт не знайдено, або він вам не належить. | Порожнє тіло або об’єкт problem |
429 | Забагато запитів. | Дивіться нижче розділ про обмеження частоти запитів. |
Обмеження частоти запитів #
Частота запитів обмежена. На запит понад ліміт API відповідає 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. |
| 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
Частота запитів обмежена. Зачекайте, потім надішліть запит знову, а цикли окремих викликів замініть одним пакетним запитом.