СОПКА/ РОЙ
Интеграционные интерфейсы

API v1 и протокол ROY

Продукт: СОПКА.РойВерсия: 1.0.0Агент: 1.0.0Редакция: 14.08.2026
Правообладатель ПО: Общество с ограниченной ответственностью «Каннам». ИНН 2543020645, ОГРН 1132543001502. Правообладатель.
Скачать PDF

Общие положения

Внешний базовый путь сервера - /roy. В API v1 интерфейсы разделены по границе доверия: Agent API используется DLP-агентами, Owner API предназначен владельцу всей платформы, а Workspace API зарезервирован для будущего пользовательского API рабочих областей. Веб-интерфейс продолжает использовать cookie-сессию, CSRF-защиту и ролевую модель workspace.

Версии текущего контракта

КомпонентТекущая версия
Windows-агент1.0.0
ROY protocol1; клиент и сервер в текущей сборке поддерживают только protocol v1.
Agent HTTP APIv1, канонический префикс /roy/api/v1/.
Policy schema1
Capabilities schema1

Версия программы агента не обязана совпадать с версией протокола. При несовместимой версии protocol/API сервер отклоняет агентский запрос. Совместимые добавления полей не требуют создания v2; новая версия создаётся только при несовместимом изменении контракта.

Контуры API v1

КонтурПрефиксАутентификация и назначение
Agent API/roy/api/v1/...Регистрационный ключ при первичной регистрации, затем device token клиента. Только обмен агент-сервер.
Owner API/roy/api/v1/owner/...Отдельный Bearer token владельца платформы. Доступ ко всем users, workspaces и clients.
Workspace API/roy/api/v1/workspaceNamespace зарезервирован, но пользовательские методы пока не реализованы.

Agent API v1

Текущий Windows-агент использует только API v1. Основные маршруты:

МетодМаршрутНазначение
POST/roy/api/v1/client_registerПервичная регистрация клиента.
POST/roy/api/v1/client_heartbeatHeartbeat, runtime-состояние и fallback доставки команд.
GET/roy/api/v1/client_commandsПолучение ожидающих команд.
POST/roy/api/v1/client_commands/<id>/ackСтатус выполнения команды.
GET/roy/api/v1/get_policies/<client_id>Подписанный policy bundle.
POST/roy/api/v1/upload_logsПакет событий агента.
POST/roy/api/v1/upload_screenshotЗагрузка снимка экрана.
POST/roy/api/v1/browser_eventСобытия браузерного канала.
GET/POST/roy/api/v1/agent/...Версия, скачивание и статусы обновления агента.

Owner API v1

Owner API - административный интерфейс владельца всей COPKA ROY. Он не использует пользовательскую веб-сессию. Каждый разрешённый запрос обязан содержать Authorization: Bearer <token>. Сетевой режим и токен задаются только через переменные окружения.

COPKA_ROY_OWNER_API_ACCESS=localhost
COPKA_ROY_OWNER_API_TOKEN=CHANGE_ME_TO_LONG_RANDOM_OWNER_API_TOKEN
RATE_LIMIT_OWNER_API=120/minute

COPKA_ROY_OWNER_API_ACCESS: disabled скрывает API с 404; localhost разрешает loopback; private разрешает loopback и приватные IP; public разрешает внешние IP. Bearer token обязателен во всех режимах, кроме того что при disabled API вообще недоступен.

МетодМаршрутНазначение
GET/roy/api/v1/ownerМетаданные Owner API.
GET/roy/api/v1/owner/systemСостояние сервера и общие счётчики.
GET/POST/roy/api/v1/owner/usersСписок и создание пользователей.
GET/roy/api/v1/owner/users/<id>Карточка пользователя и memberships.
GET/PATCH/PUT/roy/api/v1/owner/users/<id-or-login>/billingОплата, plan_status и paid_until.
GET/roy/api/v1/owner/workspacesВсе рабочие области.
GET/PATCH/roy/api/v1/owner/workspaces/<id>Карточка workspace; переключение active/disabled.
GET/roy/api/v1/owner/clientsВсе DLP-клиенты; поддерживается фильтр workspace_id.
GET/roy/api/v1/owner/clients/<client_id>Карточка конкретного клиента.

Старые маршруты /local-admin и /local/users сохранены только как временные compatibility aliases. Для нового кода следует использовать только /api/v1/owner.

Workspace API v1

COPKA_ROY_WORKSPACE_API_ENABLED=false
RATE_LIMIT_WORKSPACE_API=120/minute

Маршруты /roy/api/v1/workspace и /roy/api/v1/workspace/status пока зарезервированы. При выключенном API сервер возвращает 503 workspace_api_disabled; если включить флаг - 501 workspace_api_not_implemented. Доступ к данным workspace через этот API пока не публикуется.

Лимиты API

Owner и Workspace API имеют независимые лимиты: RATE_LIMIT_OWNER_API и RATE_LIMIT_WORKSPACE_API. Формат: 120/minute, 10/second, 1000/hour или 5000/day. Owner API ограничивается по IP и endpoint ещё до проверки Bearer token, чтобы смена неверных токенов не позволяла обходить ограничение.

Socket.IO и команды

Socket.IO работает по ресурсу /roy/socket.io. Для агента realtime-канал является основным способом быстрой доставки команд, а HTTP heartbeat остаётся fallback. Команда имеет идентификатор и состояние queued, delivered, running, затем completed либо конечную ошибку. Комнаты изолированы по workspace/client, а идентификатор клиента определяется серверной socket identity.

Форматы и безопасность