API TGProxy Panel: токены, права и примеры

Создайте персональный API-токен

Войдите в свою панель и откройте «Настройки» → «API-токены». Укажите имя, срок действия и права, необходимые интеграции. Срок по умолчанию — 30 дней; можно выбрать целое число от 1 до 365 дней. У каждой учётной записи может быть до 50 действующих токенов. Наблюдатели могут создавать токены только для чтения.

Скопируйте секрет tgwp_… до закрытия окна создания: он показывается только один раз. Панель хранит его хеш SHA-256 и открытый префикс, поэтому восстановить секрет из списка токенов нельзя. Храните его в хранилище секретов интеграции или переменной окружения; не добавляйте в исходный код, логи и общедоступные снимки экрана.

Отправляйте запросы по HTTPS на адрес своей установленной панели, например https://panel.example.com/api/v1. На tgproxypanel.com находится документация, а не API управления вашей панелью.

Передавайте один заголовок Authorization: Bearer <токен>. После проверки персонального Bearer-токена cookie и X-CSRF-Token не нужны. Некорректный или повторяющийся заголовок Authorization не заменяется авторизацией через браузерный сеанс. Поддержка токенов не меняет политику CORS панели; эти примеры запускаются на сервере или в командной строке.

Отзовите ненужный токен в «Настройки» → «API-токены». Просроченные и отозванные токены перестают работать. Смена пароля отзывает все ваши персональные токены; удаление учётной записи делает её токены недействительными. Список показывает срок действия и последнее использование; время использования обновляется не чаще раза в минуту.

Права токена и роль учётной записи

Каждый запрос должны разрешать и права токена, и текущая роль учётной записи. Права записи не включают права чтения автоматически. Изменение роли действует на последующие запросы. Наборы «Только чтение» и «Полные права» выбирают разрешения; полные права всё равно ограничены ролью учётной записи и каталогом методов ниже.

Чтение чувствительных данных требует права записи даже для метода GET: это секреты пользователей, ссылки прокси и QR-коды, команды установки серверов и секреты регистрации. Право чтения не даёт доступа к этим значениям. Нужное разрешение для каждого адреса указано в каталоге.

Создание, просмотр и отзыв токенов, управление учётными записями, смена пароля и 2FA, резервные копии и реквизиты сервиса страниц подписки требуют браузерного сеанса. Персональный токен не может выпустить другой токен или управлять этими операциями. Токены агентов, внешних проверок, метрик и сервиса подписки имеют отдельное назначение и не заменяются персональным токеном.

В журнале изменений идентификатор персонального токена записывается в api_token_id: это позволяет узнать, какая интеграция внесла изменение, не сохраняя секрет в журнале.

curl: чтение сервера и управление пользователями

Замените адрес и UUID на значения из своей панели. Загрузите токен из хранилища секретов; значение ниже — пример для замены. Чтение сервера и списка пользователей требует nodes:read и users:read. Создание, приостановка и возобновление доступа требуют users:write и роли владельца или администратора.

Задайте параметры подключения

export TGWP_PANEL_URL='https://panel.example.com'
export TGWP_API_TOKEN='tgwp_replace_with_your_token'
export TGWP_NODE_ID='replace-with-node-uuid'
export TGWP_KEY_ID='replace-with-user-uuid'

Прочитайте сервер и список активных пользователей

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $TGWP_API_TOKEN" \
  "$TGWP_PANEL_URL/api/v1/nodes/$TGWP_NODE_ID"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $TGWP_API_TOKEN" \
  "$TGWP_PANEL_URL/api/v1/keys?state=active&page=1&per_page=50"

Создайте личный доступ

curl --fail-with-body --silent --show-error \
  -X POST "$TGWP_PANEL_URL/api/v1/keys" \
  -H "Authorization: Bearer $TGWP_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data "{\"label\":\"Automation example\",\"type\":\"PERSONAL\",\"node_ids\":[\"$TGWP_NODE_ID\"],\"expires_at\":null}"

Обязательны label, type и хотя бы один UUID в node_ids. Тип задаётся в верхнем регистре: PERSONAL или SHARED. expires_at: null означает отсутствие срока доступа пользователя; для ограничения укажите будущую дату в формате RFC 3339. Это отдельный срок, не срок действия API-токена. Ответ — HTTP 201 с объектом пользователя; скопируйте его id в TGWP_KEY_ID. Ответ создания может содержать секреты и ссылки пользователя: сохраняйте их конфиденциально.

Приостановите и возобновите доступ

curl --fail-with-body --silent --show-error \
  -X POST -H "Authorization: Bearer $TGWP_API_TOKEN" \
  "$TGWP_PANEL_URL/api/v1/keys/$TGWP_KEY_ID/disable"

curl --fail-with-body --silent --show-error \
  -X POST -H "Authorization: Bearer $TGWP_API_TOKEN" \
  "$TGWP_PANEL_URL/api/v1/keys/$TGWP_KEY_ID/enable"

Оба запроса возвращают HTTP 200 с обновлённым пользователем. После этих примеров доступ включён. Возобновление не продлевает истёкший срок и не отменяет отзыв доступа.

Python без внешних библиотек

Скрипт использует те же переменные окружения и права, что и примеры curl. Он читает сервер, проходит по страницам активных пользователей, затем создаёт пользователя с доступом на семь дней, приостанавливает и возобновляет его доступ. Сохраните код в example.py и запустите python3 example.py. Скрипт печатает идентификаторы и состояние вместо полного ответа создания.

import json
import os
from datetime import datetime, timedelta, timezone
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

base = os.environ["TGWP_PANEL_URL"].rstrip("/") + "/api/v1"
token = os.environ["TGWP_API_TOKEN"]
node_id = os.environ["TGWP_NODE_ID"]
if not base.startswith("https://"):
    raise ValueError("Use the HTTPS address of your own panel")

def api(method, path, body=None):
    headers = {"Authorization": "Bearer " + token}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode("utf-8")
    req = Request(base + path, data=data, headers=headers, method=method)
    try:
        with urlopen(req, timeout=30) as response:
            raw = response.read()
            return json.loads(raw) if raw else None
    except HTTPError as exc:
        raw = exc.read()
        try:
            error = json.loads(raw).get("error", {})
        except (ValueError, AttributeError):
            error = {"code": "http_error", "message": "Non-JSON response"}
        raise RuntimeError(
            f"HTTP {exc.code}: {error.get('code')}: "
            f"{error.get('message')}; fields={error.get('fields', {})}"
        ) from None

node = api("GET", "/nodes/" + node_id)
print(node["name"], node["status"])
page = 1
while True:
    result = api("GET", "/keys?" + urlencode({
        "state": "active", "page": page, "per_page": 50
    }))
    for user in result["items"]:
        print(user["id"], user["label"], user["state"])
    if not result["items"] or page * result["per_page"] >= result["total"]:
        break
    page += 1

expires = datetime.now(timezone.utc) + timedelta(days=7)
user = api("POST", "/keys", {
    "label": "Automation example", "type": "PERSONAL",
    "node_ids": [node_id], "expires_at": expires.isoformat()
})
print("Created user:", user["id"])
api("POST", "/keys/" + user["id"] + "/disable")
api("POST", "/keys/" + user["id"] + "/enable")

Списки, фильтры и пагинация

Ответы списков содержат items; параметры пагинации зависят от конкретного метода.

GET /keys возвращает {items, total, page, per_page}. Запрашивайте страницы до достижения total или пустого массива items. Список может измениться во время обхода; не меняйте отфильтрованных пользователей посреди чтения страниц.

Применение изменений и повтор запросов

Создание и изменение пользователя ставит изменения конфигурации его серверов в очередь; успешный HTTP-ответ ещё не означает, что прокси их применил. Проверяйте nodes[].profile_sync пользователя, поля dirty, last_apply_at сервера и GET /nodes/{id}/jobs. История заданий требует nodes:write, поскольку содержит исходные логи и ошибки. У заданий есть status, started_at, finished_at и error; состояния — queued, running, ok, failed и rolled_back.

POST /nodes/{id}/apply требует nodes:write и отвечает HTTP 202 с {"queued": true}. Идентификатор задания в ответе отсутствует. Проверяйте сервер и последние задания с разумным интервалом, например пять секунд, и общим ограничением времени. При ошибке задания изучите её причину: повторная постановка в очередь сама по себе её не объяснит.

Ограничивайте время запроса. Повторяйте чтение после временных сетевых или серверных ошибок с ограниченной задержкой. Не повторяйте вслепую создание пользователей, смену секретов и другие изменения: потерянный ответ может следовать за успешной операцией. Сначала проверьте результат, чтобы избежать дубликатов или нежелательных изменений.

HTTP-статусы и ответы об ошибках

Успешный ответ может содержать JSON или другой описанный формат, например PNG или текст Prometheus. У HTTP 204 тела ответа нет. Ошибки используют такой JSON; fields присутствует при ошибках проверки полей:

{
  "error": {
    "code": "validation",
    "message": "invalid input",
    "fields": {
      "node_ids": "bind at least one node"
    }
  }
}

Каталог методов и разрешений

Каждый адрес ниже отсчитывается от домена вашей панели и включает /api/v1. Каталог и спецификация OpenAPI 3.0.3 для скачивания формируются из явной политики доступа персональных токенов в серверном коде. Адреса вне каталога недоступны персональным токенам. Ограничение «только владелец» действует дополнительно к разрешениям.

Серверы

Пользователи

Мониторинг

Сайты

Оформление

Настройки

Аудит