Permission

Represents a granular authorization rule that grants the ability to perform a specific action on a specific entity or resource within the system. Permissions are the atomic units of access control, typically following patterns like 'entity.action' (e.g., 'users.read', 'invoices.write', 'reports.delete'). This entity supports both entity-level permissions (applies to all instances of an entity type) and instance-level permissions (applies to a specific entity instance via entityId). It enables fine-grained access control, supports attribute-based access control (ABAC), row-level security, and can be assigned directly to users. Permissions serve as the foundation for authorization policies across enterprise applications, APIs, multi-tenant SaaS platforms, and complex business systems.

12 properties

Schema

Properties

Property	Type	Mode	Description	Required
entity	KernelModel	stored	Reference to the entity type this permission applies to	Required
entityId	string	stored	Optional specific entity instance ID for row-level permissions (null for entity-level permissions that apply to all instances) Example: `"user_123"`	Optional
action	PermissionAction	stored	The action that can be performed on the entity (reference to PermissionAction entity)	Required
name	string	calculated	Computed unique identifier in 'entity.action.name' format (e.g., 'users.read', 'invoices.approve') or 'entity.entityId.action.name' for instance-level permissions	Optional
label	string	stored	Human-readable display name for the permission Example: `"Read Users"`	Required
description	string	stored	Detailed description of what this permission allows Example: `"Allows reading user information including profiles and contact details"`	Optional
scope	string	stored	Scope or context where this permission applies Values: `global, organization, department, team, own` Example: `"organization"`	Optional
conditions	json	stored	Optional conditions or constraints for this permission (e.g., time-based, attribute-based rules)	Optional
isSystem	boolean	stored	Whether this is a system-defined permission that cannot be modified or deleted Example: `true`	Optional
isActive	boolean	stored	Whether this permission is currently active and can be used. When a permission is inactive, all RolePermission grants for this permission become effectively inactive regardless of their individual isActive calculated state, implementing cascade deactivation for security purposes. Example: `true`	Optional
category	PermissionCategory	stored	Category for organizing and grouping related permissions (reference to PermissionCategory entity)	Optional
metadata	json	stored	Additional metadata for permission configuration	Optional

Examples

Example 1

{
  "@type": "Permission",
  "entity": {
    "@type": "KernelModel",
    "name": "User"
  },
  "action": {
    "@type": "PermissionAction",
    "name": "read",
    "label": "Read"
  },
  "label": "Read Users",
  "description": "View user profiles and information",
  "scope": "organization",
  "isSystem": true,
  "isActive": true,
  "category": {
    "@type": "PermissionCategory",
    "name": "user-management",
    "label": "User Management"
  }
}

Example 2

{
  "@type": "Permission",
  "entity": {
    "@type": "KernelModel",
    "name": "User"
  },
  "action": {
    "@type": "PermissionAction",
    "name": "update",
    "label": "Update"
  },
  "label": "Update Users",
  "description": "Modify existing user accounts",
  "scope": "organization",
  "isSystem": true,
  "isActive": true,
  "category": {
    "@type": "PermissionCategory",
    "name": "user-management",
    "label": "User Management"
  }
}

Example 3

{
  "@type": "Permission",
  "entity": {
    "@type": "KernelModel",
    "name": "Invoice"
  },
  "action": {
    "@type": "PermissionAction",
    "name": "approve",
    "label": "Approve"
  },
  "label": "Approve Invoices",
  "description": "Approve invoices for payment",
  "scope": "organization",
  "conditions": {
    "maxAmount": 10000,
    "requiresSecondApprover": false
  },
  "isSystem": false,
  "isActive": true,
  "category": {
    "@type": "PermissionCategory",
    "name": "financial",
    "label": "Financial Operations"
  }
}

Example 4

{
  "@type": "Permission",
  "entity": {
    "@type": "KernelModel",
    "name": "Report"
  },
  "action": {
    "@type": "PermissionAction",
    "name": "read",
    "label": "Read"
  },
  "label": "View Reports",
  "description": "Access and view business reports",
  "scope": "department",
  "isSystem": true,
  "isActive": true,
  "category": {
    "@type": "PermissionCategory",
    "name": "analytics",
    "label": "Data Analytics"
  }
}

Example 5

{
  "@type": "Permission",
  "entity": {
    "@type": "KernelModel",
    "name": "Profile"
  },
  "action": {
    "@type": "PermissionAction",
    "name": "update",
    "label": "Update"
  },
  "label": "Update Own Profile",
  "description": "Update own user profile information",
  "scope": "own",
  "isSystem": true,
  "isActive": true,
  "category": {
    "@type": "PermissionCategory",
    "name": "user-management",
    "label": "User Management"
  }
}

Example 6

{
  "@type": "Permission",
  "entity": {
    "@type": "KernelModel",
    "name": "Invoice"
  },
  "entityId": "invoice_12345",
  "action": {
    "@type": "PermissionAction",
    "name": "approve",
    "label": "Approve"
  },
  "label": "Approve Specific Invoice",
  "description": "Permission to approve a specific invoice (row-level security)",
  "scope": "own",
  "isSystem": false,
  "isActive": true,
  "category": {
    "@type": "PermissionCategory",
    "name": "financial",
    "label": "Financial Operations"
  }
}