API ключи

​

Три ключа, необходимые большинству развёртываний

​

Разрешения

Примечание: Два действительных разрешения предназначены только для человека/панели управления и не могут быть предоставлены API ключу: orgs:admin (администрирование экземпляра, только для операторов) и keys:update. Запрос POST /keys или PATCH /keys/:id, пытающийся предоставить любое из них, отклоняется с кодом HTTP 422. Смотрите строку keys:update ниже, чтобы понять, почему ключ-носитель может создавать ключи, но никогда их не редактирует.

​

Приём и запрос событий

​

Сеансы и оценки

​

Панели управления

​

Сохранённые запросы (SQL редактор)

​

AI ассистент

​

API ключи

​

Пользователи панели управления

​

Операционные параметры

​

Оповещения и инциденты

​

Аудиты

Примечание: Чтобы дать ключу поверхность аудита, явно предоставьте audits:*. Смотрите Примечания об обновлении и обратной совместимости, чтобы узнать, как существующие получатели были мигрированы при появлении Audits.

Конечная точка средства выбора получателей GET /alerts/recipients (в которой указаны адреса электронной почты участников, которых редактор оповещений может уведомить), доступна держателем либо alerts:read либо alerts:write, так что редакторы оповещений могут заполнить средство выбора без предоставления users:read.

Просмотрелю панели управления требуется как dashboards:read (для загрузки сохранённых представлений), так и evaluations:read (показатели здоровья вычисляются из данных оценки). Предоставьте dashboards:write для позволить пользователю создавать или редактировать панели управления, и dashboards:delete для их удаления.

/health и /auth/* (запрос OTP, проверка OTP, проверка сеанса, выход) по замыслу не требуют аутентификации; это процесс входа и проверка работоспособности. GET /access-granters требует действительный ключ, но без конкретного разрешения, поэтому любой зарегистрировавшийся пользователь может увидеть, какие администраторы могут контактировать об изменениях доступа.

​

Наборы разрешений

• DEFAULT_USER_PERMISSIONS (право, предварительно выбранное, когда администратор открывает + новый пользователь) по умолчанию использует набор standard.
• Флаг --set на agenteye-orgctl (управление участниками организации) запускает участника из именованного набора, который вы затем можете точно настроить с помощью --add / --remove.

Примечание: Если набор включает разрешение, которое не может быть назначено ключу (например, пользовательский набор, несущий keys:update), инициализация ключа из этого набора отбрасывает неназначаемые токены; сервер иначе отклонил бы ключ с HTTP 422. Пользователи панели управления не подвергаются этому ограничению.

​

Ключ начальной загрузки администратора

​

Область действия организации

​

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

​

Ключ коллектора (только приём)

curl -s -X POST http://your-server/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-collector",
    "key": "your-collector-secret",
    "permissions": ["events:add"]
  }'

​

Ключ панели управления (только чтение)

curl -s -X POST http://your-server/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dashboard",
    "key": "your-dashboard-secret",
    "permissions": ["events:read", "keys:read"]
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "prod-collector",
  "permissions": ["events:add"],
  "created_at": "2026-04-01T12:00:00Z"
}

​

Перечисление ключей

curl -s http://your-server/keys \
  -H "Authorization: Bearer $ADMIN_KEY"

​

Отключение ключа

curl -s -X POST http://your-server/keys/<id>/disable \
  -H "Authorization: Bearer $ADMIN_KEY"

​

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

curl -s -X POST http://your-server/keys/<id>/regenerate \
  -H "Authorization: Bearer $ADMIN_KEY"

​

Управление ключами в панели управления

​

Рекомендуемая структура ключей

Примечание: Ключ ассистента инициализирован автоматически сервером из переменной окружения AGENT_API_KEY (тот же секрет, который агент представляет как AGENTEYE_API_KEY); нет ручного этапа создания ключей и нет задействованного ключа администратора. Его разрешения зафиксированы в исходном коде, поэтому область действия не может быть расширена неправильной конфигурацией: читать через события / оценки / панели управления, плюс dashboards-write и queries-read / write / run для потока автора с возможностью попросить AI написать запрос. Все SQL по-прежнему проходит через ту же роль только для чтения и охранявший путь SQL, что и написанный пользователем запрос, поэтому это расширяет поверхность создания, а не поверхность данных; деструктивные операции (queries:delete, dashboards:delete) намеренно остаются вне ключа ассистента. Как ключ admin, он защищён: не может быть отключен или восстановлен через API ключей, только ротирован путём изменения AGENT_API_KEY и перезагрузки. Пользователи панели управления дополнительно нуждаются в разрешении agent:use для просмотра и использования ассистента. Если вы включите самоинструментирование, дайте ассистенту отдельный ключ только для events:add.

​

Примечания об обновлении и обратной совместимости

Когда Audits был выпущен, существующие получатели были расширены вдоль тех же форм ролей, как оповещения: каждый пользователь и набор разрешений, держащий alerts:read, получили audits:read, и каждый держатель alerts:write получил audits:write. Существующие API ключи не были расширены. Явно предоставьте audits:* ключу, если ему нужна поверхность аудита.

Сохранённые права устаревшего токена alerts:ack анализируются как incidents:ack, так что дежурные сохраняют доступ без повторного создания ключей. Токен больше не может быть назначен из редактора пользователей панели управления; матрица предлагает incidents:ack вместо этого.

​

Следующие шаги

• Python SDK: как ваш код агента аутентифицируется при отправке событий.
• Безопасность: как работают вход, контроль доступа и изоляция данных для каждой организации.