Permission

Represents a specific authorization to perform an action on a resource within the system. Permissions are the atomic units of access control - the smallest, indivisible rights that can be granted or denied. Each permission typically follows the pattern of 'resource:action' like 'users:delete' or 'reports:view', making it clear what operation is allowed on which entity. Permissions can be simple (binary yes/no) or complex with conditions and constraints. For example, 'documents:edit' might include conditions like 'only documents you created' or 'only during business hours'. The system evaluates permissions at runtime to make access decisions, checking if the current user has the required permission through their roles, groups, or direct assignment. Permissions are versioned to track changes over time, which is crucial for audit trails and compliance. They can be tagged for organization (like 'dangerous', 'pii_access', 'financial') helping administrators understand the risk level. Modern systems might have hundreds or thousands of granular permissions, providing precise control over every feature and data element. This granularity is essential for implementing the principle of least privilege and meeting regulatory requirements like GDPR or HIPAA.

24 properties

Schema

Properties

Property	Type	Mode	Description	Required
permissionId	uuid	stored	Unique identifier for this permission	Required
code	string	stored	Unique machine-readable permission identifier Example: `"users.profile.edit"`	Required
name	string	stored	Human-readable permission name Example: `"Edit User Profiles"`	Required
description	string	stored	Detailed explanation of what this permission allows Example: `"Allows editing user profile information including name, email, and preferences"`	Optional
resource	string	stored	The resource or entity this permission applies to Example: `"users"`	Required
action	string	stored	The action allowed on the resource Example: `"edit"`	Required
scope	string	enum	Scope of the permission Values: `global, organization, department, team, self, custom`	Optional
category	string	stored	Category for organizing permissions Example: `"user_management"`	Optional
riskLevel	string	enum	Risk assessment of granting this permission Values: `low, medium, high, critical`	Optional
requiresMfa	boolean	stored	Whether this permission requires two-factor authentication	Optional
requiresApproval	boolean	stored	Whether using this permission needs approval	Optional
isSystem	boolean	stored	Whether this is a system permission that cannot be modified	Optional
isDangerous	boolean	stored	Whether this permission can cause data loss or security issues	Optional
conditions	string	stored	JSON conditions that must be met for permission to apply Example: `"{\"ownership\":\"creator\",\"status\":\"draft\"}"`	Optional
dataFilters	string	stored	JSON filters limiting what data this permission applies to Example: `"{\"department\":\"self\",\"created_after\":\"30_days_ago\"}"`	Optional
allowedFields	string	stored	JSON array of specific fields this permission covers Example: `"[\"name\",\"email\",\"phone\"]"`	Optional
deniedFields	string	stored	JSON array of fields explicitly excluded Example: `"[\"ssn\",\"creditCard\"]"`	Optional
dependencies	string	stored	JSON array of other permissions required Example: `"[\"users.view\",\"users.list\"]"`	Optional
tags	string	stored	JSON array of tags for categorization Example: `"[\"pii\",\"gdpr\",\"audit\"]"`	Optional
version	integer	stored	Version number for tracking changes	Optional
isActive	boolean	stored	Whether this permission is currently available	Optional
deprecatedAt	DateTime	stored	When this permission will be removed	Optional
createdAt	DateTime	stored	When this permission was defined	Required
metadata	string	stored	Additional configuration data	Optional

Examples

Example 1

{
  "@type": "Permission",
  "permissionId": "perm_users_delete",
  "code": "users.delete",
  "name": "Delete Users",
  "description": "Permanently delete user accounts and all associated data. This action cannot be undone and triggers GDPR data removal processes.",
  "resource": "users",
  "action": "delete",
  "scope": "organization",
  "category": "user_management",
  "riskLevel": "critical",
  "requiresMfa": true,
  "requiresApproval": true,
  "isSystem": false,
  "isDangerous": true,
  "conditions": "{\"user_status\":[\"inactive\",\"suspended\"],\"account_age_days\":30}",
  "dependencies": "[\"users.view\",\"users.deactivate\"]",
  "tags": "[\"dangerous\",\"gdpr\",\"audit\",\"compliance\"]",
  "version": 2,
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "metadata": "{\"audit_retention_days\":2555,\"requires_legal_review\":true}"
}

Example 2

{
  "@type": "Permission",
  "permissionId": "perm_reports_view",
  "code": "reports.view",
  "name": "View Reports",
  "description": "View and download generated reports and analytics dashboards",
  "resource": "reports",
  "action": "view",
  "scope": "department",
  "category": "analytics",
  "riskLevel": "low",
  "requiresMfa": false,
  "requiresApproval": false,
  "isSystem": false,
  "isDangerous": false,
  "dataFilters": "{\"department\":\"same_as_user\",\"classification\":[\"public\",\"internal\"]}",
  "deniedFields": "[\"salary\",\"performance_rating\",\"ssn\"]",
  "tags": "[\"analytics\",\"read_only\"]",
  "version": 1,
  "isActive": true,
  "createdAt": "2024-01-15T10:00:00Z"
}