AiHummer
English▾
Log in
v1.0.x▾
v1.0.xstable
{ }Swagger
Security/RBAC & scoped API keys

RBAC & scoped API keys

v1.0.x · updated 2026-07-07

AiHummer protects its admin surface with role-based access control and scoped API keys. Roles decide who a person is allowed to be; scoped keys let you hand a piece of automation only the privileges it actually needs, instead of a key that can do everything.

Roles

Access to the admin API and admin UI is governed by roles. A role determines which resource groups a principal may view and which they may change.

Roles are managed on the admin UI’s “Roles” page. Out of the box there are built-in roles — owner (everything), admin, operator and member — which are read-only (marked with a “Built-in” badge; they cannot be edited or deleted). Beyond those you can create custom roles: the role form takes a name, a description and a permission grid — read/write checkboxes for each of ~19 resource domains (agents, conversations, tools, secrets, plugins, settings, approvals, API keys and so on; “write” automatically implies “read”). Each role shows how many subjects use it; a role that is assigned to anyone cannot be deleted until the assignments are removed.

Combine roles with the other controls on this site — IP allowlist, enterprise SSO and the audit log — so that every admin action is both authorized and recorded.

Scoped API keys

API keys carry scopes that constrain what the key can do. The defined scopes are:

Scope Grants
chat The end-user OpenAI-compatible endpoint (the legacy default for existing keys).
admin:read Read-only access to admin resources (GET /v1/admin/*: settings, conversations, analytics, etc.).
admin:write Mutating admin API calls (POST/PUT/DELETE /v1/admin/*).
mcp The published MCP endpoint (POST /v1/mcp).
a2a The published Agent-to-Agent endpoint (POST /a2a/message).
* Full access to everything (the true full-access scope).

In addition, a generic <area>:* wildcard works: admin:*, for example, grants every admin action but does not grant chat, mcp or a2a — it is not a separately defined scope, just a case of the wildcard. Only * grants full access to all surfaces.

Scopes were introduced by migration 0073. Existing keys keep working; new keys can be minted with a narrow scope so that, for example, a dashboard that only reads metrics never holds a key that could change settings.

[!TIP] Apply least privilege: a monitoring or reporting integration should get an admin:read key, not admin:write — let alone *. Reserve * for keys that genuinely need access to every surface.

Choosing the right scope

  • Chat clients (calling the OpenAI-compatible endpoint) → chat.
  • Read-only integrations (dashboards, exporters, status checks) → admin:read.
  • Automation that creates or edits resources (provisioning agents, importing knowledge, managing schedules) → admin:write.
  • MCP and A2A clients → mcp and a2a respectively.
  • Break-glass / full access → *, held by as few keys as possible and rotated regularly.

[!WARNING] A scoped key is still a credential to the admin API. Store it in the secrets vault or your own secret manager, never in source control, and rotate it if it may have been exposed.

How keys are managed

Admin API keys are managed through the admin API (/v1/admin/apikeys) and the admin UI, where you mint a key, assign its scope, and revoke it when it is no longer needed. Because the admin API itself is protected by OIDC and the IP allowlist, minting a key is an authenticated, audited operation.

Where to next