Skip to content

Roles & Permissions

AegisAI implements role-based access control (RBAC) with five hierarchical roles. Permissions are enforced at the API layer via require_permission dependencies and reflected in the dashboard UI.

Role Hierarchy

flowchart TB
    SA[super_admin<br/>Rank 5] --> AD[admin<br/>Rank 4]
    AD --> SEC[security_analyst<br/>Rank 3]
    SEC --> DEV[developer<br/>Rank 2]
    DEV --> VW[viewer<br/>Rank 1]

Higher-ranked roles inherit all capabilities of lower ranks within their permission scope, plus additional privileges.

Role Definitions

Role Rank Scope Typical User
super_admin 5 Platform-wide, all tenants Platform operator
admin 4 Full tenant management IT security lead
security_analyst 3 Audit, anomalies, HITL SOC analyst
developer 2 Agent development ML engineer
viewer 1 Read-only observability Compliance auditor

Permission Matrix

Super Admin

Full access to all resources across all tenants (*:*).

Admin

Resource Permissions
users create, read, update, delete, change_role
policies create, read, update, delete
agents create, read, update, delete
audit read, export
anomalies read, confirm
hitl read, approve, reject
dashboard read

Security Analyst

Resource Permissions
audit read, export
anomalies read, confirm
policies read
dashboard read
hitl read, approve, reject

Developer

Resource Permissions
agents create, read, update
policies read
audit read
dashboard read

Viewer

Resource Permissions
dashboard read
audit read

Tenant Isolation

Rule Description
Same-tenant access Users can only access resources in their tenant_id
Super Admin bypass super_admin can access any tenant
Cross-tenant denial API returns 403 Forbidden for wrong-tenant access
Role ceiling Users cannot assign roles above their own rank

Authentication Methods by Role

Method Header Used By
JWT Authorization: Bearer <token> Dashboard users (all roles)
User API Key X-API-Key: <user-key> Programmatic user access
Tenant API Key X-API-Key: <tenant-key> Agent/SDK operations
Admin Key X-Admin-Key: <key> Tenant provisioning only

JWT tokens embed sub (user ID), tenant_id, and role claims. WebSocket connections authenticate via ?token=<jwt>.

API Enforcement

Permissions are checked in app/core/rbac.py:

PERMISSIONS = {
    "admin": {
        "users": ["create", "read", "update", "delete", "change_role"],
        "policies": ["create", "read", "update", "delete"],
        # ...
    },
    # ...
}

Endpoints use dependency injection:

ReadPolicies = Depends(require_permission("policies", "read"))
WritePolicies = Depends(require_permission("policies", "create"))

Dashboard UI Enforcement

The frontend hides navigation items and action buttons based on the user's role:

Page Minimum Role
Dashboard Viewer
Audit Viewer
Agents Developer
Policies (read) Developer
Policies (write) Admin
Anomalies Security Analyst
HITL Security Analyst
Users Admin
Settings All roles

Unauthorized access redirects to the 403 Forbidden page.

Assigning Roles

Only Admins and Super Admins can change roles:

curl -X PUT http://localhost:8000/api/v1/users/<user_id>/role \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"role": "security_analyst"}'

Assignment Rules

  1. Cannot assign super_admin unless you are super_admin
  2. Cannot assign a role with rank higher than your own
  3. Role changes take effect on next API request (JWT role claim refreshed on re-login)

Best Practices

Recommendations

  1. Principle of least privilege — assign the lowest role that meets job requirements
  2. Separate duties — developers manage agents; analysts review audit/anomalies
  3. Limit super_admin — reserve for platform operators only
  4. Audit role changes — all role assignments are logged
  5. Review quarterly — audit user roles and remove stale accounts