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. 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 admin API keys
Admin API keys carry scopes that constrain what the key can do. There are
three scopes:
Scope
Grants
admin:read
Read-only access to admin resources (view settings, conversations, analytics, etc.).
admin:write
Read and write access to admin resources.
admin:*
Full admin access (equivalent to all admin scopes).
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 or admin:*. Reserve admin:* for keys
that genuinely need to mutate every resource group.
Choosing the right scope
Read-only integrations (dashboards, exporters, status checks) →
admin:read.
Automation that creates or edits resources (provisioning agents, importing
knowledge, managing schedules) → admin:write.
Break-glass / full administration → admin:*, 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
Enterprise SSO — authenticate the humans
behind the roles via SAML, LDAP, SCIM or OIDC.
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. Combine
roles with the other controls on this site — [IP allowlist](/en/v1.0/security/network-audit-airgapped),
[enterprise SSO](/en/v1.0/security/enterprise-sso) and the
[audit log](/en/v1.0/security/network-audit-airgapped) — so that every admin
action is both authorized and recorded.
## Scoped admin API keys
Admin API keys carry **scopes** that constrain what the key can do. There are
three scopes:
| Scope | Grants |
|---|---|
| `admin:read` | Read-only access to admin resources (view settings, conversations, analytics, etc.). |
| `admin:write` | Read **and** write access to admin resources. |
| `admin:*` | Full admin access (equivalent to all admin scopes). |
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` or `admin:*`. Reserve `admin:*` for keys
> that genuinely need to mutate every resource group.
## Choosing the right scope
- **Read-only integrations** (dashboards, exporters, status checks) →
`admin:read`.
- **Automation that creates or edits resources** (provisioning agents, importing
knowledge, managing schedules) → `admin:write`.
- **Break-glass / full administration** → `admin:*`, 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](/en/v1.0/security/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](/en/v1.0/security/enterprise-sso), minting a key is
an authenticated, audited operation.
## Where to next
- [Enterprise SSO](/en/v1.0/security/enterprise-sso) — authenticate the humans
behind the roles via SAML, LDAP, SCIM or OIDC.
- [Network, audit & air-gapped](/en/v1.0/security/network-audit-airgapped) —
restrict where the admin API can be reached from and keep an audit trail.
- [Secrets vault](/en/v1.0/security/vault) — where to keep the keys you mint.
AiHummer