API

Ошибки: {"error":"message"}. Host — ваш base URL ноды.

Auth (JWT кабинета)

POST /v1/auth/register · POST /v1/auth/login → { token, user }

{
  "email": "user@example.com",
  "name": "User",
  "password": "password123",
  "password_confirm": "password123"
}

GET /v1/me — JWT (в ответе есть logging_enabled, default false). PATCH /v1/me/settings — { "logging_enabled": true|false }. Пароль ≥ 8, email с @.

API keys

JWT. Raw key (pk_live_…) только в ответе create.

POST /v1/api-keys
{ "name": "main", "scopes": ["proxy", "fetch", "ingress"] }

GET    /v1/api-keys
DELETE /v1/api-keys/{id}

В data-plane:

X-Api-Key: pk_live_...
# или
Authorization: Bearer pk_live_...

Proxy

Scope proxy. Метод/body/большинство заголовков → upstream.

GET|POST|… /v1/proxy?url=https://example.com/path
GET|POST|… /v1/proxy/https://example.com/path
Шлюз: X-Api-Key. Upstream: X-Upstream-Authorization → Authorization; X-Upstream-X-Foo → X-Foo. Если шлюз уже через X-Api-Key, обычный Authorization (не pk_live) тоже считается upstream.

Fetch

Scope fetch. GET-прокси, те же routing-заголовки.

GET /v1/fetch?url=https://example.com/file.zip

Routing headers

Header Смысл
X-Chain ru->de, ru->de->nl. Перекрывает mode.
X-Proxy-Mode direct | chain
X-Exit-Node регион exit или auto
X-Entry-Node entry для chain
X-Upstream-* заголовки на target

В ответе часто есть X-Proxy-Chain, X-Exit-Node. Не пробрасываются на target: X-Api-Key, routing-заголовки, hop-by-hop.

Origins (CDN)

JWT. Публично: /o/{slug}/… → {target_base}/…

POST /v1/origins
{
  "slug": "jsdelivr",
  "target_base": "https://cdn.jsdelivr.net",
  "exit_node": "auto",
  "entry_node": "ru",
  "proxy_mode": "chain"
}

GET /v1/origins
PATCH /v1/origins/{id}
DELETE /v1/origins/{id}

Ingress

JWT на управление. Публично: ANY /in/{token} → forward_url.

POST /v1/ingress
{
  "name": "payments",
  "forward_url": "https://backend.example.ru/webhook",
  "exit_node": "auto",
  "entry_node": "ru",
  "proxy_mode": "chain"
}
# 201: token, public_url

GET /v1/ingress
DELETE /v1/ingress/{id}

Nodes / health

GET /health
GET /v1/nodes                 # JWT или API key
GET /v1/nodes?host=api.telegram.org

# Логи (JWT; по умолчанию выкл.)
# Включить: PATCH /v1/me/settings  { "logging_enabled": true }
GET /v1/logs
GET /v1/logs?key_id={api_key_id}
GET /v1/logs?node=de
GET /v1/nodes/{id}/logs

Логирование access-логов по умолчанию выключено (logging_enabled: false). Пока выключено, записи не пишутся, а чтение возвращает пустой список. В кабинете — переключатель; через API — PATCH /v1/me/settings. В логах нет body и сырых секретов. Фильтр key_id — по ключу из GET /v1/api-keys; node / /v1/nodes/{id}/logs — логи с ноды или конкретной ноды.

Коды

Код Когда
400 нет/кривой url, loop в chain
401 нет или плохой ключ
403 SSRF / нет scope
502 upstream или peer

Internal

/internal/* + X-Internal-Token — только peer-форвард между нодами. Клиентам не нужно.

Шифрование и trust model

Источник: SECURITY.md. В проде: TLS client→entry, HTTPS peer’ов (REQUIRE_PEER_TLS=true), sealed headers, SSRF filter.

cliententry TLS / HTTPS
entryexit HTTPS + X-Sealed-Headers AES-256-GCM
exittarget HTTPS
Уровень Механизм
client → entry TLS (HTTPS)
entry → exit HTTPS в PEER_NODES
секреты на hop X-Sealed-Headers AES-256-GCM (ключ = SHA-256(INTERNAL_TOKEN))
exit → target https:// URL
хранение API keys SHA-256; пароли bcrypt
Примеры Доступ