Ключи API и роли

Все пути API начинаются с /api на том же адресе, что и консоль. Программа аутентифицируется ключом API в заголовке X-API-Key:

curl https://soc.example.com/api/findings?limit=20 \
  -H "X-API-Key: legit_…"

Ключ принадлежит одному тенанту и видит только его данные.

Создание ключа

Администратор создаёт ключи в Настройки → API-ключи. Ключ показывается один раз — при создании; скопируйте его тогда. Он начинается с legit_, а хранится только его хеш SHA-256.

У каждого ключа есть срок действия. Ключ живёт не дольше года с момента создания; более поздняя дата сокращается до этого предела.

Ключами можно управлять и через API с ключом или сессией ADMIN:

Метод	Путь	Что делает
POST	/api/auth/api-keys	Создать ключ: {"role": "ANALYST", "scopes": ["read", "write"], "expires_at": "2027-01-01T00:00:00Z"}
GET	/api/auth/api-keys	Список ключей: id, роль, области, создан, последнее использование, срок. Сам ключ — никогда.
DELETE	/api/auth/api-keys/{id}	Немедленно отозвать ключ

Создание и отзыв ключа записываются в журнал аудита.

Ключ принадлежит не только арендатору, но и человеку, который его создал. Если этого человека приостановили или удалили, ключ перестаёт работать, а при понижении его роли понижается и ключ. Ключ не может создать другой ключ. GET /api/auth/api-keys показывает создателя в поле created_by; у ключей, созданных до 6 ноября 2026, его нет, они работают до истечения срока, поэтому замените их.

Роли

У ключа одна роль, и она задаёт потолок:

Роль	Может
VIEWER	Читать алерты, события, расследования и отчёты
ANALYST	Всё, что VIEWER, а также отправлять события, разбирать алерты, запрашивать действия реагирования и одобрять запросы других людей
ADMIN	Всё, что ANALYST, а также управлять пользователями, ключами и агентами и одобрять команды, поставленные агенту напрямую

Области доступа

В пределах своей роли ключ делает только то, что разрешают его области:

Область	Нужна для
read	Запросов GET
write	Запросов POST, PUT, PATCH и DELETE
admin	Любого запроса, которому нужна роль ADMIN. У ключа ADMIN она обязательна.

Запрос, который роль разрешает, а области — нет, отклоняется с 403 и API key scope is not sufficient.

Другие способы входа

Способ	Кто использует
X-API-Key: legit_…	Скрипты и другие системы
Authorization: Bearer <JWT>	Сессии, вошедшие через /api/auth/login
Cookie сессии	Консоль в браузере. Запросы, меняющие состояние, должны также передавать заголовок X-CSRF-Token, совпадающий с cookie csrf_token.

Запросам с ключом API или bearer-токеном заголовок CSRF не нужен.

У агентов свои ключи

Агент Windows не использует ключ API из настроек. Он получает собственный ключ при регистрации по токену подключения, и этот ключ открывает только эндпоинты самого агента. См. Подключение конечной точки Windows.