> ## Documentation Index > Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt > Use this file to discover all available pages before exploring further. # Permission Key Standard > Version: 1.0.0 Date: 2026-01-12 Status: Active **Version:** 1.0.0\ **Date**: 2026-01-12\ **Status**: Active ## Overview This document defines the standard pattern and conventions for permission keys used throughout the Encore Health OS platform. Permission keys control access to features, entities, and actions within the system. ## Standard Pattern ### Format ``` {module}.{entity}.{action} ``` ### Components 1. **Module** (required): The module identifier (e.g., `hr`, `fa`, `rh`, `fw`, `it`, `gr`, `fm`, `lo`, `pf`) 2. **Entity** (required): The entity or feature being accessed (e.g., `employees`, `bills`, `residents`, `forms`, `assets`) 3. **Action** (required): The action verb describing the permission (e.g., `view`, `create`, `edit`, `manage`, `admin`) ### Examples ``` hr.employees.view # View employees hr.employees.create # Create new employees hr.employees.edit # Edit existing employees fa.bills.approve # Approve bills rh.residents.manage # Full CRUD on residents fw.forms.admin # Full control including settings it.tickets.view # View IT tickets ``` ## Action Verb Definitions ### View Permissions | Action | Description | Use Case | | ------- | ------------------------------------ | ------------------------------------------- | | `.view` | Read-only access to view entity | Viewing list or detail pages | | `.list` | Access to list view (subset of view) | When list access differs from detail access | **Note:** `.view` is preferred over `.list` unless there's a specific need to distinguish list vs. detail access. ### Create/Edit Permissions | Action | Description | Use Case | | --------- | --------------------- | ------------------------------------------------ | | `.create` | Create new records | Creating new entities | | `.edit` | Edit existing records | Editing existing entities | | `.delete` | Delete records | Deleting entities (rare, usually part of manage) | ### Manage Permissions | Action | Description | Use Case | | --------- | --------------------------------------------------- | ------------------------------------------------------------------------ | | `.manage` | Full CRUD operations (create, read, update, delete) | Preferred over separate create/edit/delete permissions for most entities | **Guideline:** Use `.manage` for most entities unless there's a specific business need to separate create/edit/delete permissions. ### Administrative Permissions | Action | Description | Use Case | | -------- | ---------------------------------------------------------------------------- | ------------------------------------------------- | | `.admin` | Full control including settings, configuration, and administrative functions | Module settings, configuration, advanced features | **Guideline:** Use `.admin` for: * Module-level settings * Configuration pages * Administrative functions * Advanced features requiring elevated privileges ### Workflow Permissions | Action | Description | Use Case | | ---------- | ------------------------ | ------------------------------------------- | | `.approve` | Approval workflow access | Approving requests, workflows, transactions | | `.reports` | Report generation access | Generating and viewing reports | ### Specialized Permissions | Action | Description | Use Case | | --------- | --------------------------------- | ---------------------------------- | | `.cab` | Change Advisory Board access | IT change management CAB review | | `.manage` | Template/configuration management | Managing templates, configurations | ## Module-Specific Examples ### HR Module ``` hr.employees.view # View employees hr.employees.create # Create new employees hr.employees.edit # Edit existing employees hr.employees.manage # Full CRUD on employees hr.credentials.view # View credentials hr.credentials.manage # Manage credentials (CRUD) hr.credentials.admin # Credential types and requirements configuration hr.performance.view # View performance data hr.performance.manage # Manage performance reviews hr.performance.admin # Performance settings and configuration hr.payroll.view # View payroll data hr.payroll.admin # Payroll runs and settings hr.leave.view # View leave data hr.leave.manage # Manage leave policies hr.timesheets.view # View timesheets hr.timesheets.approve # Approve timesheets hr.benefits.view # View benefits hr.benefits.admin # Benefits configuration ``` ### Finance & Accounting Module ``` fa.accounts.view # View chart of accounts fa.accounts.manage # Manage accounts fa.bills.view # View bills fa.bills.create # Create bills fa.bills.approve # Approve bills fa.bills.manage # Full CRUD on bills fa.transactions.view # View transactions fa.transactions.create # Create transactions fa.reports.view # View financial reports fa.reports.generate # Generate reports fa.admin # Full module access ``` ### Recovery Housing Module ``` rh.residents.view # View residents rh.residents.create # Create new residents rh.residents.manage # Full CRUD on residents rh.beds.view # View bed management rh.beds.manage # Manage beds rh.admissions.view # View admissions rh.admissions.create # Create admissions rh.compliance.view # View compliance rh.compliance.manage # Manage compliance requirements ``` ### Forms & Workflow Module ``` fw.forms.view # View forms fw.forms.create # Create forms fw.forms.edit # Edit forms fw.submissions.view # View submissions fw.submissions.manage # Manage submissions fw.automations.view # View automations fw.automations.manage # Manage automations fw.approvals.view # View approval inbox fw.approvals.approve # Approve requests fw.templates.view # View templates fw.templates.manage # Manage templates fw.admin # Full module access ``` ### IT Operations Module ``` it.assets.view # View IT assets it.assets.create # Create assets it.assets.edit # Edit assets it.tickets.view # View tickets it.tickets.create # Create tickets it.tickets.manage # Manage tickets it.licenses.view # View licenses it.licenses.create # Create licenses it.licenses.edit # Edit licenses it.security.view # View security dashboard it.security.manage # Manage security items it.changes.view # View change requests it.changes.create # Create change requests it.changes.approve # Approve changes it.changes.cab # CAB review access it.changes.manage # Manage change templates it.reports.view # View reports it.reports.create # Create reports ``` ## Permission Key Consistency ### Standardization Rules 1. **Use `.manage` for CRUD operations** unless there's a specific business need to separate create/edit/delete 2. **Use `.admin` for settings and configuration**, not for regular CRUD operations 3. **Use `.view` for read access**, prefer over `.list` unless distinction is needed 4. **Use `.approve` for approval workflows**, not `.manage` or `.admin` 5. **Use module-level `.admin`** for full module access and settings ### Common Inconsistencies to Avoid ❌ **Wrong:** ``` hr.credentials.admin # Used for CRUD operations fa.bills.manage # Used for settings fw.forms.admin # Used for regular editing ``` ✅ **Correct:** ``` hr.credentials.manage # For CRUD operations hr.credentials.admin # For credential types/requirements configuration fa.bills.manage # For CRUD operations fa.bills.approve # For approval workflow fw.forms.edit # For editing forms fw.admin # For module settings ``` ## Migration Guide ### Standardizing Existing Permissions When standardizing existing permission keys: 1. **Audit current usage** - Identify all permission keys in use 2. **Map to standard pattern** - Determine correct action verb 3. **Update code references** - Update all code using old permission keys 4. **Update database** - Migrate permission assignments 5. **Update documentation** - Update navigation worksheets and specs ### Example Migration **Before:** ``` hr.credentials.admin # Used for both CRUD and configuration ``` **After:** ``` hr.credentials.manage # For CRUD operations hr.credentials.admin # For configuration only ``` ## Navigation Integration Permission keys are used in navigation to control visibility: ```typescript theme={null} { label: "Employees", route: "/hr/employees", permission: "hr.employees.view", // Required permission } ``` Navigation items are hidden if the user lacks the required permission. ## See Also * `src/platform/permissions/constants.ts` - Permission definitions * `src/platform/modules/module-registry.ts` - Navigation permission usage * `AGENTS.md §Permissions System Patterns` - Permission system patterns * `specs/pf/PF-30-permissions-system-v2.md` - Permissions system specification