Role
Defines a named collection of permissions that can be assigned to users or groups, implementing Role-Based Access Control (RBAC) in the system. Roles are the cornerstone of scalable permission management - instead of assigning individual permissions to thousands of users, you create roles like 'Editor', 'Manager', or 'Admin' and assign appropriate permissions to each role. Users then inherit all permissions from their assigned roles. This dramatically simplifies access management, especially in large organizations where many people have similar job functions. Roles can be hierarchical, where a 'Senior Manager' role might inherit all permissions from 'Manager' plus additional elevated privileges. System roles (like 'Super Admin') are built-in and protected from modification, while custom roles can be created to match specific organizational needs. Each role has a priority level to resolve conflicts when a user has multiple roles with contradicting permissions. Roles can be scoped to specific contexts - for example, someone might be an 'Admin' for one department but 'Viewer' for another. This entity makes it easy to implement least-privilege access, conduct access reviews, and maintain compliance with security policies by providing a clear, auditable structure for who can do what in the system.
Properties
| Property | Type | Mode | Description | Required |
|---|---|---|---|---|
| roleId | uuid | stored | Unique identifier for this role | Required |
| code | string | stored | Machine-readable identifier used in code and APIs Example: | Required |
| name | string | stored | Human-friendly display name Example: | Required |
| description | string | stored | Detailed explanation of the role's purpose and responsibilities Example: | Optional |
| type | string | enum | Classification of the role Values: Example: | Optional |
| scope | string | stored | Context where this role applies (global, org-specific, etc.) Example: | Optional |
| isSystem | boolean | stored | Whether this is a built-in role that cannot be modified | Optional |
| isDefault | boolean | stored | Whether new users automatically receive this role | Optional |
| isAssignable | boolean | stored | Whether this role can be assigned to users | Optional |
| requiresMfa | boolean | stored | Whether users need two-factor authentication for this role | Optional |
| requiresApproval | boolean | stored | Whether role assignment needs manager approval | Optional |
| maxAssignments | integer | stored | Maximum number of users who can have this role (null for unlimited) | Optional |
| priority | integer | stored | Resolution order when permission conflicts occur (higher wins) | Optional |
| parentRoleId | uuid | stored | Parent role from which permissions are inherited | Optional |
| expirationDays | integer | stored | Days until role assignment expires (null for permanent) | Optional |
| allowedIpRanges | string | stored | JSON array of IP ranges where this role is active Example: | Optional |
| allowedTimeWindows | string | stored | JSON array of time windows when role is active Example: | Optional |
| tags | string | stored | JSON array of tags for categorization Example: | Optional |
| isActive | boolean | stored | Whether this role is currently active | Optional |
| createdAt | DateTime | stored | When this role was created | Required |
| createdBy | User | stored | User who created this role | Optional |
| updatedAt | DateTime | stored | Last modification timestamp | Optional |
| metadata | string | stored | Additional configuration in JSON format | Optional |
Examples
Example 1
{
"@type": "Role",
"roleId": "role_abc123",
"code": "FINANCE_MANAGER",
"name": "Finance Manager",
"description": "Full access to financial data, reports, and budgeting tools. Can approve expenses up to $50,000 and manage team members in finance department.",
"type": "department",
"scope": "department:finance",
"isSystem": false,
"isDefault": false,
"isAssignable": true,
"requiresMfa": true,
"requiresApproval": true,
"maxAssignments": 5,
"priority": 75,
"parentRoleId": "role_employee",
"expirationDays": 365,
"allowedIpRanges": "[\"10.0.0.0/8\",\"vpn.company.com\"]",
"allowedTimeWindows": "[{\"days\":[\"mon\",\"tue\",\"wed\",\"thu\",\"fri\"],\"start\":\"07:00\",\"end\":\"19:00\",\"timezone\":\"America/New_York\"}]",
"tags": "[\"finance\",\"management\",\"sensitive\",\"sox_compliance\"]",
"isActive": true,
"createdAt": "2024-01-01T00:00:00Z",
"createdBy": "admin_789",
"metadata": "{\"approval_chain\":[\"dept_head\",\"cfo\"],\"training_required\":\"finance_security_101\"}"
}Example 2
{
"@type": "Role",
"roleId": "role_def456",
"code": "GUEST_VIEWER",
"name": "Guest Viewer",
"description": "Read-only access to public content and basic application features. Cannot modify any data or access sensitive information.",
"type": "system",
"scope": "global",
"isSystem": true,
"isDefault": true,
"isAssignable": true,
"requiresMfa": false,
"requiresApproval": false,
"maxAssignments": null,
"priority": 10,
"parentRoleId": null,
"expirationDays": 30,
"tags": "[\"public\",\"readonly\",\"guest\"]",
"isActive": true,
"createdAt": "2024-01-01T00:00:00Z",
"metadata": "{\"rate_limit\":\"100_per_hour\",\"features_disabled\":[\"export\",\"api_access\"]}"
}