Scope Levels

CORTEX RBAC uses three scope levels to control the reach of roles and permissions.

Overview

┌────────────────────────────────────────────────────────┐
│                    PLATFORM Scope                       │
│  • System administrators                               │
│  • Cross-tenant operations                             │
│  • Platform-wide configuration                         │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │               TENANT Scope                        │  │
│  │  • Tenant administrators                         │  │
│  │  • All resources within a tenant                 │  │
│  │  • Tenant-wide policies                          │  │
│  │                                                  │  │
│  │  ┌────────────────────────────────────────────┐  │  │
│  │  │          ORGANIZATION Scope                │  │  │
│  │  │  • Department managers                     │  │  │
│  │  │  • Organization-specific resources        │  │  │
│  │  │  • Team members                           │  │  │
│  │  └────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────┘

PLATFORM Scope

The highest privilege level, spanning all tenants.

Characteristics

Property	Value
Span	All tenants in the system
Users	System administrators only
Use Cases	Platform operations, tenant provisioning

Example Roles

Role	Description
SUPER_ADMIN	Full platform access
PLATFORM_OPERATOR	Infrastructure operations
SUPPORT_ADMIN	Cross-tenant support access

Platform-Level Operations

• Create and manage tenants
• View system-wide metrics
• Manage platform configuration
• Access any tenant for support

Security

Platform scope roles should be assigned to very few users. These roles have unrestricted access.

TENANT Scope

Access to all resources within a single tenant.

Characteristics

Property	Value
Span	Single tenant
Users	Tenant administrators, managers
Use Cases	Tenant administration, cross-org operations

Example Roles

Role	Description
TENANT_ADMIN	Full tenant access
TENANT_MANAGER	Limited tenant management
HR_ADMIN	Cross-org user management

Tenant-Level Operations

• Create and manage organizations
• Manage all users in the tenant
• Configure tenant settings
• View all tenant audit logs

Assignment (No Organization)

{
  "userId": "user-id",
  "roleId": "tenant-admin-id"
  // No organizationId = tenant-wide
}

ORGANIZATION Scope

Access limited to a specific organization and its children.

Characteristics

Property	Value
Span	Single organization + descendants
Users	Department managers, team members
Use Cases	Team management, departmental access

Example Roles

Role	Description
ORG_ADMIN	Full organization access
MANAGER	Team management
MEMBER	Standard member access
VIEWER	Read-only access

Organization-Level Operations

• Manage organization users
• Create sub-organizations
• Assign organization-scoped roles
• View organization audit logs

Assignment (With Organization)

{
  "userId": "user-id",
  "roleId": "org-admin-id",
  "organizationId": "engineering-id"
}

Scope Inheritance

Child organizations inherit parent permissions:

User: Jane Doe
Role: ORG_ADMIN
Organization: Engineering

Can Access:
✓ Engineering (direct)
✓ Frontend Team (child)
✓ Backend Team (child)
✓ DevOps Team (child)
✗ Sales (different branch)

Choosing the Right Scope

Use PLATFORM When

• Managing system infrastructure
• Performing cross-tenant operations
• Implementing support workflows

Use TENANT When

• Administering a single customer
• Implementing cross-department policies
• Managing tenant-wide settings

Use ORGANIZATION When

• Managing teams or departments
• Implementing least-privilege access
• Creating project-specific access

Scope Comparison

Aspect	PLATFORM	TENANT	ORGANIZATION
Data Access	All tenants	One tenant	One org + children
User Count	1-5	5-20	Many
Use Case	System ops	Business ops	Team ops
Risk Level	Highest	High	Normal

Code Examples

Check User's Scope Level

interface User {
  id: string;
  roles: {
    role: { scopeLevel: 'PLATFORM' | 'TENANT' | 'ORGANIZATION' };
    organizationId: string | null;
  }[];
}

function getHighestScope(user: User): string {
  const scopePriority = ['PLATFORM', 'TENANT', 'ORGANIZATION'];

  let highestScope = 'ORGANIZATION';
  for (const assignment of user.roles) {
    const scope = assignment.role.scopeLevel;
    if (scopePriority.indexOf(scope) < scopePriority.indexOf(highestScope)) {
      highestScope = scope;
    }
  }

  return highestScope;
}

Filter by Scope

// Get roles at specific scope level
async function getRolesByScope(
  accessToken: string,
  scopeLevel: 'PLATFORM' | 'TENANT' | 'ORGANIZATION'
) {
  const response = await fetch(
    `http://localhost:8091/roles?scopeLevel=${scopeLevel}`,
    { headers: { 'Authorization': `Bearer ${accessToken}` } }
  );
  return response.json();
}