RBAC и scoped API-ключи — AiHummer Документация

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

Роли

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

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

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

Scoped API-ключи

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

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

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

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

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

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

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

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

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

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

Куда дальше

Корпоративный SSO — аутентификация людей за ролями через SAML, LDAP, SCIM или OIDC.
Сеть, аудит и air-gapped — ограничьте, откуда доступен admin API, и ведите журнал аудита.
Vault для секретов — где хранить выпущенные ключи.