API-ключи

AgentEye использует детально настраиваемые API-ключи для управления доступом к серверу. Каждый ключ имеет одно или несколько разрешений, которые определяют его возможности.

Разрешения

Сервер поддерживает фиксированный набор разрешений; каждое из них управляет доступом к определённым HTTP маршрутам. Административный ключ имеет все разрешения; ограниченный ключ имеет подмножество, которое вы предоставляете при создании. Неизвестные строки разрешений отклоняются при создании ключа.

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

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

Разрешение	HTTP-маршруты	Что оно позволяет
`events:add`	`POST /events`	Приём пакетов событий от сборщика. Единственное разрешение, необходимое сборщику.
`events:read`	`GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export`	Запрос событий, получение списка известных окружений, получение идентификаторов моделей в данных (используется в представлении Models и фильтрах модели), расчёт совокупной задержки для тепловой карты / полос процентилей и экспорт сеанса в формате JSONL. Общие конечные точки фасетов фильтра `GET /events/environments` и `GET /events/models` доступны с либо `events:read` либо `evaluations:read`, поэтому страница сеансов (требует `evaluations:read`) переиспользует тот же фасет для каждой организации.

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

Разрешение	HTTP-маршруты	Что оно позволяет
`evaluations:read`	`GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs`	Список сеансов, чтение результатов оценки, свёрнутое состояние здоровья оценки для панелей и состояние очереди работников заданий оценки.
`evaluations:trigger`	`POST /sessions/:session_id/re-evaluate`	Ручная постановка в очередь переоценки завершённого сеанса.

Панели

Разрешение	HTTP-маршруты	Что оно позволяет
`dashboards:read`	`GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles`	Получение списка панелей, загрузка одной и чтение её плиток.
`dashboards:write`	`POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout`	Создание и редактирование панелей, добавление / редактирование / удаление плиток и переупорядочение сетки плиток.
`dashboards:delete`	`DELETE /dashboards/:id`	Удаление полной панели (удаление уровня плиток находится под `dashboards:write`).

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

Разрешение	HTTP-маршруты	Что оно позволяет
`queries:read`	`GET /queries`, `GET /queries/:id`, `GET /queries/schema`	Получение списка сохранённых запросов, загрузка одного и проверка схемы только для чтения ClickHouse, на которую ориентирован композитор.
`queries:write`	`POST /queries`, `PUT /queries/:id`	Создание и редактирование сохранённых запросов. SQL по-прежнему маршрутизируется через ту же роль только для чтения и проверки `sql_guard`, что и вызов `queries:run`.
`queries:delete`	`DELETE /queries/:id`	Удаление сохранённого запроса.
`queries:run`	`POST /queries/run`	Выполнение сохранённого или специального SQL-запроса к роли только для чтения, используемой композитором.

Помощник AI

Разрешение	HTTP-маршруты	Что оно позволяет
`agent:use`	`GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages`	Общение с помощником AI панели и управление своими (приватными) беседами. Требуется для пользователя, чтобы увидеть док помощника; собственный ключ помощника - это `dashboard-assistant` и он инициализируется отдельно (смотрите ниже).

Разрешение	HTTP-маршруты	Что оно позволяет
`keys:create`	`POST /keys`	Создание нового ограниченного API-ключа. Не предоставляет редактирование разрешений существующего ключа (это `keys:update`).
`keys:read`	`GET /keys`	Получение списка существующих ключей. Секреты никогда не возвращаются этой конечной точкой.
`keys:update`	`PATCH /keys/:id`	Редактирование разрешений существующего ключа. Разрешение только для человека/панели; оно не может быть назначено API-ключу (ключ-носитель может создавать ключи, но не может их редактировать).
`keys:disable`	`POST /keys/:id/disable`	Отзыв ключа. Защищённые ключи (`admin`, `dashboard-assistant`) нельзя отключить; поверните их через переменную окружения и перезагрузку.
`keys:regenerate`	`POST /keys/:id/regenerate`	Ротация секрета ключа. Защищённые ключи нельзя восстановить через эту маршрут.

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

Разрешение	HTTP-маршруты	Что оно позволяет
`users:create`	`POST /users`, `GET /users/defaults`	Приглашение нового пользователя панели (выдача письма + вход через OTP) и чтение набора разрешений по умолчанию, настроенного панелью и используемого для предварительного заполнения формы приглашения.
`users:read`	`GET /users`, `GET /users/:id`	Получение списка пользователей и загрузка одной записи пользователя.
`users:update`	`PUT /users/:id`	Редактирование разрешений пользователя. Обновления отправляют письмо об изменении разрешений затронутому пользователю и вступают в силу при его следующем запросе; повторный вход не требуется.
`users:delete`	`DELETE /users/:id`, `POST /users/:id/enable`	Отключение пользователя (немедленно отзывает его сеансы) и повторное включение ранее отключённого пользователя.

Эти разрешения поддерживают страницу Пользователи панели, где предоставленные области каждого члена отображаются как чипы:

Страница Пользователи: карточка на пользователя панели с адресом электронной почты, предоставленными разрешениями и элементами управления редактированием/отключением

Операционные настройки

Разрешение	HTTP-маршруты	Что оно позволяет
`settings:read`	`GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve`	Просмотр операционных настроек, управляемых панелью, и их метаданных; получение списка переопределений размера контекста для каждой модели; и разрешение эффективного окна для модели.
`settings:write`	`PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows`	Редактирование операционных настроек и добавление, изменение или удаление переопределений размера контекста для каждой модели. Изменения влияют на новые события без перезагрузки сервера.

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

Разрешение	HTTP-маршруты	Что оно позволяет
`alerts:read`	`GET /alerts`, `GET /alerts/:id`	Просмотр настроенных определений оповещений.
`alerts:write`	`POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test`	Создание, редактирование, удаление и тестовое срабатывание определений оповещений.
`incidents:read`	`GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers`	Просмотр инцидентов и их тропы сортировки.
`incidents:write`	`POST /alerts/:id/incidents`	Открытие инцидента вручную против существующего оповещения.
`incidents:ack`	`POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe`	Подтверждение, назначение, разрешение и комментирование инцидентов.

Проверки

Разрешение	HTTP-маршруты	Что оно позволяет
`audits:read`	`GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid`	Просмотр определений проверок, истории выполнения и результатов.
`audits:write`	`POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status`	Создание, редактирование, удаление и выполнение проверок; сортировка результатов (подтверждение / отключение / отклонение / разрешение / переоткрытие / назначение).

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

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

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

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

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

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

Наборы разрешений позволяют применять именованную роль вместо выбора отдельных токенов каждый раз. Вместо выбора дюжины разрешений одного за другим для каждого нового пользователя панели или API-ключа, вы выбираете набор, и каждому, кто ему назначен, присваивается согласованное, проверяемое предоставление. Редактирование пользовательского набора повторно применяет новое предоставление каждому пользователю, уже ему назначенному, поэтому изменение роли - это одно редактирование, а не обход каждого члена. Каждая организация инициализируется с тремя встроенными наборами:

Набор	Разрешения	Предназначен для
`read-only`	`events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read`	Доступ только для просмотра по всей операционной поверхности.
`standard`	всё в `read-only`, плюс `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use`	Только для чтения плюс повседневные действия дежурного: выполнение запросов, переоценка сеансов, подтверждение инцидентов и использование помощника AI.
`admin`	каждое назначаемое разрешение	Полный контроль над организацией.

Три встроенных набора неизменяемы; их имена всегда означают одно и то же, поэтому read-only, standard и admin безопасно ссылать в политике и адаптации. Оператор может создавать дополнительные пользовательские наборы для моделирования ролей, специфичных для вашей организации (например, роль “автор панели” или роль “только сборщик”). Наборы отображаются на панели и управляются через API в GET /permission-sets (список, требует users:read) и POST /permission-sets / PUT /permission-sets/:name / DELETE /permission-sets/:name (создание, редактирование, удаление пользовательского набора, требует settings:write). Удаление или редактирование встроенного набора отклоняется. Членство в наборе поддерживает две другие функции:

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

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

Начальный административный ключ

Административный ключ - это единственное корневое учётное данные, которое позволяет оператору начать доступ с нуля: с его помощью вы можете создавать каждый другой ограниченный ключ, приглашать первых пользователей панели и конфигурировать экземпляр до того, как существует какой-либо другой ключ. Это единственный ключ, который вы не создаёте через API ключей; он инициализируется из окружения, чтобы сервер был доступен при первой загрузке. Установите переменную окружения ADMIN_KEY на сервере. При каждой загрузке сервер вставляет это значение как административный ключ со всеми разрешениями. Для ротации: измените ADMIN_KEY на новый секрет и перезагрузите сервер.

Область организации

Организации сами создаются и управляются оператором вне полосы, не через этот API ключей. Жизненный цикл организации и членов (создание / переименование / удаление / очистка организации; добавление / обновление / удаление члена) осуществляется с помощью CLI agenteye-orgctl, который работает внутри модуля сервера; нет HTTP API или кнопки панели для этого. Смотрите Управление арендаторами. Что остаётся неизменным: API-ключи для каждой организации всё ещё создаются на панели (или через этот API ключей) членами организации. При развёртывании с несколькими организациями, каждый ключ, создаваемый членом организации (через этот API ключей или страницу Ключи панели), принадлежит одной организации и может только читать или писать данные этой организации; организация отмечается на ключе при создании и применяется при каждом запросе. Два начальных ключа - единственное исключение: ключ admin (инициализируется из ADMIN_KEY) и ключ dashboard-assistant (инициализируется из AGENT_API_KEY) относятся к экземпляру (они не имеют организации). Контейнер панели аутентифицируется с помощью ключа admin, чтобы он мог проксировать запросы для каждой организации от имени вошедших членов. Развёртывания с одним арендатором не нуждаются в этом; все ключи принадлежат встроенной организации default.

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

Используйте административный ключ (или любой ключ с разрешением keys:create) для создания дополнительных ограниченных ключей.

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

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

Когда вы создаёте ключ через HTTP API, вы сами предоставляете значение key; выберите надёжный секрет и сохраните его безопасно. (Панель работает по-другому: она генерирует надёжный секрет для вас и показывает его один раз при создании; смотрите Управление ключами на панели.) Ответ подтверждает, что ключ был создан:

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

Получение списка ключей

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

Секреты ключей не возвращаются в ответах списка, только ID, имена и разрешения.

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

Отключение отзывает доступ немедленно без удаления записи ключа.

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

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

Генерирует новый секрет для существующего ключа. Старый секрет немедленно становится недействительным.

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

Ответ включает новый секрет в открытом виде, показываемый только один раз.

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

Страница Ключи на панели предоставляет интерфейс для всех вышеперечисленных операций. Вам нужен ключ с разрешением keys:read, чтобы просмотреть список, и keys:create / keys:update / keys:disable / keys:regenerate для действий создания / редактирования / отключения / восстановления соответственно. Редактирование разрешений ключа (keys:update) отделено от создания (keys:create), поэтому вы можете предоставить оператору возможность создавать ключи без возможности переопределения существующих или наоборот. Административный ключ охватывает все эти действия. Когда вы создаёте ключ из панели, вы не предоставляете секрет; панель генерирует надёжный секрет для вас и отображает его один раз при создании. Скопируйте его немедленно и сохраните безопасно; он никогда больше не будет показан, точно как при восстановлении. Вы по-прежнему можете выбрать разрешения ключа напрямую или инициализировать их из набора разрешений (смотрите ниже).

Страница API-ключи: карточка на ключ, показывающая его имя, предоставленные разрешения и время создания, с действиями восстановления и отключения; защищённые ключи, такие как admin, отмечены

Ключ	Разрешения	Используется
`admin` (начальный через переменную окружения `ADMIN_KEY`)	все	Операции/настройка и контейнер панели (аутентифицируется с помощью `ADMIN_KEY`, проксирует запросы пользователей с проверками разрешений)
Ключ сборщика на хост	`events:add`	Сборщик на каждой машине агента
`dashboard-assistant` (начальный через переменную окружения `AGENT_API_KEY`)	`events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run`	Контейнер помощника AI, инициализируется автоматически, защищён; не может быть отредактирован через API
Ключ телеметрии помощника (опционально)	`events:add`	Самоинструментирование помощника AI, если включено

​Разрешения

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

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

​Панели

​Сохранённые запросы (SQL-композитор)

​Помощник AI

​API-ключи

​Пользователи панели

​Операционные настройки

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

​Проверки

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

​Начальный административный ключ

​Область организации

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

​Ключ сборщика (только приём)

​Ключ панели (только чтение)

​Получение списка ключей

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

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

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

​Рекомендуемый макет ключей