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-audit | Prometheus, Grafana, SIEM-системы и SOC-коллекторы |
| system:read / system:write | Статус узла / переключение каскада, апстримы, сервисы и security-mode | SRE-скрипты отказоустойчивости и управление демонами |
3. Полная карта эндпоинтов по 7 доменам
Все операторские маршруты сгруппированы под /<console>/api/v1 и полностью дублируют возможности веб-панели для детерминированной автоматизации:
Эндпоинты по функциональным доменам
Карта APIЕдиный REST-контур покрывает пользователей, тарифы, шейпер, каскад, телеметрию, сервисы и Corporate Gateway.
| Домен | Основные эндпоинты | Что автоматизирует |
|---|---|---|
| Пользователи и Bulk | GET/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-audit | Healthcheck, метрики 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 Gateway | GET /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 | Динамическое переключение выходных стран и автоматический контроль полосы |