AiHummer
Русский▾
ВойтиЛичный кабинет
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Безопасность/RBAC и API-ключи с ограниченными правами

RBAC и API-ключи с ограниченными правами

v1.2.x · обновлено 2026-07-21

AiHummer защищает свою административную поверхность с помощью ролевого контроля доступа (RBAC) и API-ключей с ограниченными правами. Роли определяют, кем человеку разрешено быть; ключи с ограниченным набором прав позволяют выдать части автоматизации ровно те привилегии, которые ей реально нужны, вместо ключа, который может всё.

Роли

Доступ к admin API и веб-интерфейсу управляется ролями. Роль определяет, какие группы ресурсов принципал может просматривать и какие — изменять.

Ролями управляют на странице «Роли» админ-панели. Из коробки есть встроенные роли — owner (всё), admin, operator и member — они доступны только для чтения (помечены меткой «Встроенная», их нельзя изменить или удалить). Помимо них можно создавать собственные роли: в форме роли задаются имя, описание и сетка прав — чекбоксы чтение/запись по каждому из ~19 доменов ресурсов (агенты, диалоги, инструменты, секреты, плагины, настройки, согласования, API-ключи и т.д.; «запись» автоматически включает «чтение»). У каждой роли показано, сколько субъектов её использует; роль, назначенная кому-либо, не может быть удалена, пока назначения не сняты.

Права удобнее описывать матрицей «объект → действие», а не списком. Точная сетка каждой роли видна в форме роли на странице «Роли»; вот пример матрицы для двух собственных ролей:

Домен ресурсов Роль «Аналитик» Роль «Оператор поддержки»
Диалоги (сессии) чтение чтение + запись
Аналитика чтение чтение
Одобрения — чтение + запись
Каналы — чтение
Агенты — чтение
Секреты — —
Настройки — —

При создании роли отмечайте в сетке только нужные домены: «запись» автоматически включает «чтение», а всё неотмеченное недоступно.

Сочетайте роли с остальными механизмами этого раздела — списком разрешённых IP-адресов, корпоративным SSO и журналом аудита — чтобы каждое административное действие было и авторизовано, и зафиксировано.

API-ключи с ограниченными правами

API-ключи несут наборы прав (в API — scopes), ограничивающие то, что ключ может делать. Определены следующие значения scope:

Scope Даёт
chat OpenAI-совместимый пользовательский endpoint (историческое значение по умолчанию для существующих ключей).
admin:read Доступ только на чтение к admin-ресурсам (GET /v1/admin/*: настройки, диалоги, аналитика и т.д.).
admin:write Изменяющие вызовы admin API (POST/PUT/DELETE /v1/admin/*).
mcp Публикуемый MCP-endpoint (POST /v1/mcp).
a2a Публикуемый Agent-to-Agent endpoint (POST /a2a/message).
* Полный доступ ко всему (набор прав полного доступа).

Кроме того, работает общий wildcard вида <область>:*: например, admin:* разрешает все admin-действия, но не даёт chat, mcp или a2a — это не отдельный определённый набор прав, а частный случай wildcard. Полный доступ ко всем поверхностям даёт только *.

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

[!TIP] Применяйте наименьшие привилегии: интеграция для мониторинга или отчётности должна получать ключ admin:read, а не admin:write и тем более не *. Оставляйте * для ключей, которым действительно нужен доступ ко всем поверхностям.

Выбор правильного набора прав

  • Клиенты чата (обращение к OpenAI-совместимому endpoint) → chat.
  • Интеграции только на чтение (дашборды, экспортёры, проверки статуса) → admin:read.
  • Автоматизация, создающая или меняющая ресурсы (агенты автоматического заведения, импорт знаний, управление расписаниями) → admin:write.
  • MCP- и A2A-клиенты → mcp и a2a соответственно.
  • Break-glass / полный доступ → *, у как можно меньшего числа ключей и с регулярной ротацией.

[!WARNING] Ключ с ограниченными правами — это всё равно доступ к admin API. Храните его в хранилище секретов или в своём менеджере секретов, никогда в системе контроля версий, и меняйте, если он мог быть раскрыт.

Как управляются ключи

Admin API-ключи управляются через admin API (/v1/admin/apikeys) и веб-интерфейс, где вы выпускаете ключ, назначаете ему набор прав и отзываете, когда он больше не нужен. Поскольку сам admin API защищён OIDC и списком разрешённых IP-адресов, выпуск ключа — это аутентифицированная и аудируемая операция.

Куда дальше