> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API-ключи
> Документация по API-ключам AgentEye.
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` и он инициализируется отдельно (смотрите ниже). |
### API-ключи
| Разрешение | 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`. Смотрите [Развёртывание](/ru/agenteye/deployment).
* **Флаг `--set`** в `agenteye-orgctl` (управление членами оператора) запускает члена из именованного набора, который вы затем дополняете с помощью `--add` / `--remove`. Смотрите [Управление арендаторами](/ru/agenteye/tenant-management).
> Когда набор включает разрешение, которое не может быть назначено ключу (например пользовательский набор, содержащий `keys:update`), инициализация ключа из этого набора отбрасывает неназначаемые токены; сервер иначе отклонил бы ключ с кодом HTTP 422. Пользователи панели не подлежат этому ограничению.
***
## Начальный административный ключ
Административный ключ - это единственное корневое учётное данные, которое позволяет оператору начать доступ с нуля: с его помощью вы можете создавать каждый другой ограниченный ключ, приглашать первых пользователей панели и конфигурировать экземпляр до того, как существует какой-либо другой ключ. Это единственный ключ, который вы не создаёте через API ключей; он инициализируется из окружения, чтобы сервер был доступен при первой загрузке.
Установите переменную окружения `ADMIN_KEY` на сервере. При каждой загрузке сервер вставляет это значение как административный ключ со всеми разрешениями.
Для ротации: измените `ADMIN_KEY` на новый секрет и перезагрузите сервер.
***
## Область организации
**Организации сами создаются и управляются оператором вне полосы, не через этот API ключей.** Жизненный цикл организации и членов (создание / переименование / удаление / очистка организации; добавление / обновление / удаление члена) осуществляется с помощью **CLI `agenteye-orgctl`**, который работает внутри модуля сервера; нет HTTP API или кнопки панели для этого. Смотрите [Управление арендаторами](/ru/agenteye/tenant-management). Что *остаётся* неизменным: **API-ключи для каждой организации всё ещё создаются на панели (или через этот API ключей)** членами организации.
При развёртывании с несколькими организациями, каждый ключ, создаваемый членом организации (через этот API ключей или страницу **Ключи** панели), принадлежит **одной организации** и может только читать или писать данные этой организации; организация отмечается на ключе при создании и применяется при каждом запросе. Два начальных ключа - единственное исключение: ключ `admin` (инициализируется из `ADMIN_KEY`) и ключ `dashboard-assistant` (инициализируется из `AGENT_API_KEY`) **относятся к экземпляру** (они не имеют организации). Контейнер панели аутентифицируется с помощью ключа `admin`, чтобы он мог проксировать запросы для каждой организации от имени вошедших членов. Развёртывания с одним арендатором не нуждаются в этом; все ключи принадлежат встроенной организации `default`.
***
## Создание ключей
Используйте административный ключ (или любой ключ с разрешением `keys:create`) для создания дополнительных ограниченных ключей.
### Ключ сборщика (только приём)
```bash theme={null}
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"]
}'
```
### Ключ панели (только чтение)
```bash theme={null}
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`; выберите надёжный секрет и сохраните его безопасно. (Панель работает по-другому: она генерирует надёжный секрет для вас и показывает его один раз при создании; смотрите [Управление ключами на панели](#key-management-in-the-dashboard).) Ответ подтверждает, что ключ был создан:
```json theme={null}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "prod-collector",
"permissions": ["events:add"],
"created_at": "2026-04-01T12:00:00Z"
}
```
***
## Получение списка ключей
```bash theme={null}
curl -s http://your-server:8080/keys \
-H "Authorization: Bearer $ADMIN_KEY"
```
Секреты ключей не возвращаются в ответах списка, только ID, имена и разрешения.
***
## Отключение ключа
Отключение отзывает доступ немедленно без удаления записи ключа.
```bash theme={null}
curl -s -X POST http://your-server:8080/keys//disable \
-H "Authorization: Bearer $ADMIN_KEY"
```
***
## Восстановление ключа
Генерирует новый секрет для существующего ключа. Старый секрет немедленно становится недействительным.
```bash theme={null}
curl -s -X POST http://your-server:8080/keys//regenerate \
-H "Authorization: Bearer $ADMIN_KEY"
```
Ответ включает новый секрет в открытом виде, **показываемый только один раз**.
***
## Управление ключами на панели
Страница **Ключи** на панели предоставляет интерфейс для всех вышеперечисленных операций. Вам нужен ключ с разрешением `keys:read`, чтобы просмотреть список, и `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` для действий создания / редактирования / отключения / восстановления соответственно. Редактирование разрешений ключа (`keys:update`) отделено от создания (`keys:create`), поэтому вы можете предоставить оператору возможность создавать ключи без возможности переопределения существующих или наоборот. Административный ключ охватывает все эти действия.
Когда вы создаёте ключ из панели, вы не предоставляете секрет; панель генерирует надёжный секрет для вас и отображает его **один раз** при создании. Скопируйте его немедленно и сохраните безопасно; он никогда больше не будет показан, точно как при восстановлении. Вы по-прежнему можете выбрать разрешения ключа напрямую или инициализировать их из набора разрешений (смотрите ниже).
***
## Рекомендуемый макет ключей
| Ключ | Разрешения | Используется |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `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, если включено |
> **Ключ помощника.** Ключ помощника **инициализируется автоматически** сервером из переменной окружения `AGENT_API_KEY` (тот же секрет, который агент представляет как `AGENTEYE_API_KEY`); нет ручного шага создания ключа и не требуется административный ключ. Его разрешения фиксированы в исходном коде, поэтому область не может быть расширена неправильной конфигурацией: чтение по событиям / оценкам / панелям, плюс dashboards-write и queries-read / write / run для потока написания запроса Спроси AI. Весь SQL по-прежнему проходит через ту же роль только для чтения и проверки `sql_guard`, что и пользовательский запрос, поэтому это расширяет *поверхность написания*, а не поверхность данных; деструктивные операции (`queries:delete`, `dashboards:delete`) намеренно остаются вне ключа помощника. Как и ключ `admin`, он **защищён**: не может быть отключен или восстановлен через API ключей, только повёрнут изменением `AGENT_API_KEY` и перезагрузкой. Пользователи панели **дополнительно** нуждаются в разрешении `agent:use`, чтобы увидеть и использовать помощника. Если вы включаете самоинструментирование, дайте помощнику отдельный ключ, содержащий только `events:add`.