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

Permission matrix

Insufficient permissions return:

{
  "error": "forbidden",
  "message": "Role 'viewer' is not authorized for action 'agent:create'"
}

Key management

Create keys for different roles

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

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

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

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

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

Key expiration

Keys can optionally expire:

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

Expired keys are treated as invalid at validation time.

Rotate keys

hoziron 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