Формат ключа
apm_<48 base62> (SHA-256)
RBAC-права
full, read + 12 гранулярных
Охват API
7 доменов + /enterprise
События и метрики
HMAC Webhooks + Prometheus

1. Авторизация, генерация ключей и модель безопасности

Каждый узел Apium Cloud OS предоставляет изолированный REST API под префиксом консоли (/<console>/api/v1/...). Авторизация поддерживается через заголовок X-API-Key: apm_... или стандартный Authorization: Bearer apm_....

  • Гибридная энтропия при выпуске: при создании ключа в панели браузер собирает координаты и тайминги движения мыши (client_entropy), смешивает их с crypto.getRandomValues и передаёт на сервер, где они объединяются с двумя 32-символьными CSPRNG-строками и наносекундным timestamp через SHA-256, формируя токен формата apm_<48 base62>.
  • Однократный показ и хеширование: открытый ключ apm_... показывается оператору ровно один раз в момент генерации; в таблице api_keys хранится только его SHA-256 хеш.
  • Сетевые и временные ограничения: для каждого ключа можно задать белый список IP-адресов (allowed_ips) и срок действия (expires_at).
  • Аудит и OpenAPI: все обращения фиксируются в журнале аудита (GET /api/v1/api-audit), а из модального окна API выгружается готовая спецификация apium-cloud-os-openapi.json для генерации клиентских SDK.

2. Матрица прав (RBAC Scopes) и ограничения редакций

Вместо одного «супертокена на всё» Apium Cloud OS реализует ролевую модель на базе комбинируемых scope-прав (передаются списком через запятую). На бесплатной редакции Lite разрешён только режим read; глобальный ключ full и любые права на запись (:write) работают начиная с редакций Pro, Ultra и Extra.

Гранулярные scope-права и профили API-ключей

Контроль доступа

Комбинируйте глобальные и ресурсные права для изоляции биллинга, HR-скриптов, мониторинга и SRE-автоматизации.

Scope / МаскаУровень доступаТиповой профиль применения
fullПолный доступ на чтение и запись ко всем доменам (Pro/Ultra/Extra)Мастер-оркестратор или выделенный IaC-контроллер
readГлобальное чтение всех ресурсов (кроме /system/config)Централизованный инвентаризатор или внешняя BI-аналитика
users:read / users:writeЧтение аккаунтов и сессий / создание, продление, отзыв, кик и bulk-операцииTelegram-боты, SaaS-биллинг, HR/IAM-онбординг
groups:read / groups:writeПросмотр групп / назначение и изменение групповых политикАвтоматизация доступа по отделам компании
plans:read / plans:writeЧтение тарифов / создание и удаление тарифов, применение шейпераСинхронизация тарифной сетки и лимитов скорости
webhooks:read / webhooks:writeСписок подписок / регистрация и удаление HMAC-вебхуковАвтоконфигурация шины событий для новых интеграций
monitoring:readДоступ к /overview, /health, /metrics, /sessions, /logs, /api-auditPrometheus, Grafana, SIEM-системы и SOC-коллекторы
system:read / system:writeСтатус узла / переключение каскада, апстримы, сервисы и security-modeSRE-скрипты отказоустойчивости и управление демонами

3. Полная карта эндпоинтов по 7 доменам

Все операторские маршруты сгруппированы под /<console>/api/v1 и полностью дублируют возможности веб-панели для детерминированной автоматизации:

Эндпоинты по функциональным доменам

Карта API

Единый REST-контур покрывает пользователей, тарифы, шейпер, каскад, телеметрию, сервисы и Corporate Gateway.

ДоменОсновные эндпоинтыЧто автоматизирует
Пользователи и BulkGET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extendСоздание аккаунтов, массовый выпуск ключей и групповое продление
Управление аккаунтомGET /users/:id/config, POST /users/:id/extend|revoke|restore|reset-traffic|rotate-token|kick, PUT /users/:id/group|expiration|restrictions, GET /users/:id/sessionsВыдача конфигов, ротация токенов, кик активных сессий и лимиты
Тарифы и шейперGET/POST /plans, DELETE /plans/:id, POST /shaper/applyУправление тарифными планами и применение правил ограничения скорости
Каскад и апстримыPUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-trafficСмена режима каскада, проверка выходных узлов, вкл/выкл и сброс счётчиков
Мониторинг и аудитGET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-auditHealthcheck, метрики Prometheus, обрыв сессий и журнал аудита API
Вебхуки и API-ключиGET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:idПрограммное управление подписчиками вебхуков и ротацией ключей
Сервисы, защита и лицензияPOST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activateУправление службами, разбан IP в Fail2ban, обновление AdBlock и лицензия
Corporate GatewayGET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:idВыделенный контур управления пользователями и шлюзами Corporate Gateway

4. Примеры запросов, подписок и событий

A. Provisioning и продление пользователей

Создавайте учётные записи сразу по тарифному плану (plan_id), продлевайте срок действия (add_days), добавляйте квоту (add_quota_gb) и автоматически восстанавливайте доступ (auto_restore: true) без перезапуска транспортных ядер:

curl -X POST -H "X-API-Key: apm_..." \
  -H "Content-Type: application/json" \
  -d '{"username":"client_9042","plan_id":1}' \
  https://node.apium.cloud/<console>/api/v1/users

curl -X POST -H "Authorization: Bearer apm_..." \
  -H "Content-Type: application/json" \
  -d '{"add_days":30,"add_quota_gb":100,"auto_restore":true}' \
  https://node.apium.cloud/<console>/api/v1/users/42/extend

B. Публичный эндпоинт подписок (стандартные заголовки клиентов)

Клиентские приложения (v2rayNG, Nekobox, Streisand, Hiddify) забирают единую токенизированную ссылку, получая Base64-профили и стандартные заголовки остатка трафика и срока действия:

GET /<console>/api/v1/subscriptions/<sub_token>

< HTTP/1.1 200 OK
< Profile-Title: Apium Cloud OS
< Profile-Update-Interval: 12
< Subscription-Userinfo: upload=104857600; download=2147483648; total=107374182400; expire=1798761600

C. Вебхуки с криптографической подписью HMAC-SHA256

Чтобы ваш биллинг или CRM не опрашивали серверы в цикле, Apium отправляет события в реальном времени с заголовками X-Apium-Event и X-Apium-Signature для проверки подлинности:

POST https://billing.example.com/webhooks/apium
X-Apium-Event: user.created
X-Apium-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

{
  "event": "user.created",
  "timestamp": "2026-11-14T12:30:00Z",
  "data": { "user": { "id": 42, "username": "client_9042", "protocol": "hysteria2" } }
}

D. Метрики Prometheus (GET /api/v1/metrics)

Отдельный ключ со scope monitoring:read отдаёт метрики в нативном формате Prometheus для построения дашбордов в Grafana и настройки алертов по активным сессиям и задержке (RTT) каскадных апстримов:

# TYPE apium_active_sessions gauge
apium_active_sessions 1248
# TYPE apium_users_total gauge
apium_users_total{status="active"} 3410
# TYPE apium_upstream_latency_ms gauge
apium_upstream_latency_ms{id="1",name="NL-AMS-01"} 18

5. Практические сценарии применения и интеграции

Как компании и сервисы используют API Apium Cloud OS

Сценарии интеграции

Типовые производственные архитектуры поверх REST API, гранулярных ключей, Webhooks и Prometheus.

СценарийИспользуемые механизмы APIПрактический эффект
Telegram-боты и SaaS-биллингКлюч users:write + POST /users, /users/bulk-create, /extend, Subscriptions + WebhooksМгновенная выдача доступа после оплаты, автопродление и синхронизация статусов
Корпоративный HR / IAM-онбордингusers:write + groups:write + POST /users/:id/kick и /enterprise/...Автоматическая выдача VPN при найме и моментальный отзыв доступа при увольнении
SRE и мониторинг флота узловКлюч monitoring:read + GET /metrics, /health, /api-audit + allowed_ipsДашборды в Grafana и алерты без риска утечки прав на запись
Автоматизация каскада и шейпераsystem:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/applyДинамическое переключение выходных стран и автоматический контроль полосы