Role-Based Access Control (RBAC)

What you'll accomplish: Understand the role hierarchy, assign appropriate permissions, and manage API keys for teams and services.

Roles

Six roles are defined in hoziron-core-types::auth::permissions::Role:

auditor is a real, first-class role (Role::Auditor in code) even though it isn't listed in hoziron-cli auth create-key --help's example text — it is accepted by --role auditor the same as the other five.

Permission matrix

This table is generated from the platform's actual PERMISSION_MATRIX (crates/platform/hoziron-core-types/src/auth/permissions.rs) — every Action variant that exists is listed below with the exact roles authorized to perform it. There is no agent:create or workflow:create action: agents and workflows enter the system only via catalog:install (install-from-package), not a runtime create endpoint.

Notable patterns:

• The credential vault (vault:read/vault:manage) is Admin-only, deliberately excluding auditor — even a compliance role cannot list or write vault entries. This is the same bar as auth:key_management. See Credentials.
• catalog:uninstall and destructive integration/registry removal are gated at catalog:manage/integration:manage (Operator+), separate from the lower-bar catalog:install/integration:read used for routine installs.
• auditor never appears on a write action — it is the read-plus-audit role, not a superset of operator.
• audit:read is defined but not currently wired to any route — GET /security/audit is gated on security:audit, not audit:read (both land on the same Admin/Auditor pair today, so this doesn't change who can do what, but don't go looking for a separate audit:read-gated endpoint).

Insufficient permissions return:

{
  "error": "forbidden",
  "message": "Role 'viewer' cannot perform 'agent:start'"
}

Key management

Create keys for different roles

# Admin key (full access)
hoziron-cli auth create-key --role admin --name "platform-admin"

# Operator key for CI/CD
hoziron-cli auth create-key --role operator --name "deploy-bot" --expires-in 90d

# Developer key for a team member
hoziron-cli auth create-key --role developer --name "alice"

# Service key for automated integrations
hoziron-cli auth create-key --role service --name "webhook-handler"

# Viewer key for monitoring dashboards
hoziron-cli auth create-key --role viewer --name "grafana-readonly"

# Auditor key for a compliance officer (read-only, plus audit trail access)
hoziron-cli auth create-key --role auditor --name "compliance-review"

Key expiration

Keys can optionally expire:

hoziron-cli auth create-key --role operator --name "temp-access" --expires-in 7d

Expired keys are treated as invalid at validation time.

Rotate keys

hoziron-cli auth rotate-key <key-id>

Rotation creates a new key and revokes the old one in a single operation.

Safety guardrails

• The last admin key cannot be revoked (prevents lockout)
• Key values are shown once at creation — never retrievable after
• Only the first 12 characters are stored as a prefix for identification

Best practices

• Use service role for automation — it has minimal permissions (invoke agents, run workflows)
• Set expiration on all non-admin keys
• Store keys in a secrets manager, inject via environment variables
• Create separate keys per integration (easier to revoke individually)
• Use OIDC for human users, local keys for service accounts

Next steps

• Production hardening checklist
• Enable audit trail
• Authentication setup

Related:

• Authentication
• Audit trail
• Security internals