Role-Based Access Control (RBAC)

CORTEX implements a hierarchical RBAC system with three scope levels, permission inheritance, and time-bound role assignments.

Core Concepts

Roles

A role is a named collection of permissions. Roles can be organized in a hierarchy where child roles inherit permissions from parent roles.

Permissions

A permission represents the ability to perform a specific action on a specific resource. Permissions follow the resource:action pattern (e.g., users:create, organizations:read).

Role Assignments

A role assignment links a user to a role, optionally scoped to a specific organization and with an optional expiration date.

Scope Levels

┌─────────────────────────────────────────┐
│           PLATFORM Scope                │
│   System-wide roles (e.g., SUPER_ADMIN) │
│                                         │
│  ┌────────────────────────────────────┐ │
│  │        TENANT Scope                │ │
│  │  Tenant-wide roles                 │ │
│  │  (e.g., TENANT_ADMIN, MEMBER)      │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │    ORGANIZATION Scope        │  │ │
│  │  │  Org-specific roles          │  │ │
│  │  │  (e.g., ORG_ADMIN, VIEWER)   │  │ │
│  │  └──────────────────────────────┘  │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘

Level	Description	Example Roles
PLATFORM	System-wide, across all tenants	SUPER_ADMIN
TENANT	Within a single tenant	TENANT_ADMIN, MEMBER
ORGANIZATION	Within a specific organization	ORG_ADMIN, VIEWER

Role Hierarchy Example

TENANT_ADMIN (inherits all below)
├── ORG_ADMIN (inherits all below)
│   ├── MEMBER (inherits all below)
│   │   └── VIEWER (base permissions)

When a user has the TENANT_ADMIN role, they automatically inherit all permissions from ORG_ADMIN, MEMBER, and VIEWER.

Endpoints

Method	Endpoint	Description
POST	/roles	Create role
GET	/roles	List roles
GET	/roles/:id	Get role details
PATCH	/roles/:id	Update role
DELETE	/roles/:id	Delete role
GET	/roles/:id/hierarchy	Get role hierarchy tree
POST	/permissions	Create permission
GET	/permissions	List permissions
POST	/role-assignments	Assign role to user
DELETE	/role-assignments/:id	Revoke role
GET	/users/:id/roles	Get user's roles

Security Rules

1. No Self-Escalation — Users cannot assign themselves a higher role
2. No Cross-Tenant Roles — Roles from one tenant cannot be assigned in another
3. Organization Scoping — ORG_ADMIN in Engineering cannot access Sales data
4. Immutable System Roles — Built-in system roles cannot be modified or deleted

Quick Links

• Roles — Role management and CRUD
• Permissions — Permission definitions
• Role Hierarchy — Inheritance and hierarchy
• Role Assignments — Assigning roles to users
• Scope Levels — Understanding scope levels