--- id: CON-PFM-SEC-004 name: Role feature: FEAT-PFM-SEC-04 product_area: platform module: security revision: 1 status: superseded product_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A role groups permission rules and reusable policies into an access definition that Rhythm supplies or a customer maintains. owned_by: MOD-PFM-SEC synonyms: - security role - policy (its building block) not_to_be_confused_with: - Role grant - CRM contact role - Licence facets: - name: Permission meaning: 'An application action carries tier, sensitivity and any staff-only classification.' used_for: Expressing allowed or denied work using a common vocabulary. - name: Permission catalog meaning: Released services supply the set of available permission definitions. used_for: Keeping rule choices aligned with exposed operations. - name: Policy meaning: 'A reusable named rule group combines allows, denies and supported conditions.' used_for: Sharing access definitions between job roles. - name: Built-in policy meaning: >- Release-controlled policies include generated application tiers and declared sensitive-power groups. used_for: Providing shared read-only starting definitions. - name: Custom policy and role meaning: Customer-owned definitions can be authored locally or copied with their original version recorded. used_for: Representing the customer’s own job requirements. - name: Built-in role meaning: Five customer roles and three staff roles group Rhythm’s shared policies. used_for: Supplying standard assignments for common audiences. - name: Grants-nothing label meaning: The indication identifies a role with no effective allow of its own or through active policies. used_for: Recognizing incomplete or emptied definitions. - name: Eligibility binding meaning: A custom role may identify a workspace eligibility rule and re-check interval. used_for: Deriving assignments from qualifying contact facts. relationships: - to: CON-PFM-SEC-005 statement: A role assignment connects the access definition to its holder and scope. provenance: test source: >- services-platform:modules/security/tests/e2e/console-users.e2e.spec.js#grants a role by its built-in key and answers the grant with the role it names - to: CON-PFM-SEC-001 statement: Customer-owned definitions remain local while built-in definitions are shared. provenance: test source: >- services-platform:modules/security/tests/integration/db/security-definition-integrity.integration.spec.js#refuses another customer's policy, the one way authority could cross a wall through a definition lifecycle: - state: active meaning: The definition is available for permitted use and assignment. how_it_changes: Customer creation or release reconciliation supplies an active definition. - state: archived meaning: The retained definition is unavailable for new attachment or usable grants. how_it_changes: 'The customer archives an unused definition, or a release retires a built-in.' acted_on_by: - CAP-PFM-SEC-010 - CAP-PFM-SEC-012 - CAP-PFM-SEC-013 - CAP-PFM-SEC-014 - CAP-PFM-SEC-015 visible_to: - ACT-PFM-001 - ACT-PFM-002 - ACT-PFM-004 - ACT-PFM-005 evidence: - >- Pinned services-platform references for the structured rows: modules/security/tests/e2e/console-users.e2e.spec.js; modules/security/tests/integration/db/security-definition-integrity.integration.spec.js. supersedes: [] --- # Role ## What It Is This retained record is superseded by the User Account concept, which now owns its facets. A role gives staff a reusable name for a set of access definitions. Administrator and Read Only are common examples; a customer can also describe a job such as Finance Clerk. Naming the job allows administrators to work with a meaningful grouping rather than select individual permissions for every person. The definition combines policies and, where used, inline rules. Policies provide reusable lists of allow and deny rules. Permissions identify actions in applications, and supported conditions restrict when those rules apply. A definition establishes what a role can express; a grant establishes who holds it and where it applies. Rhythm supplies shared built-in definitions through released catalogs. Customers can read those definitions and create their own, including copies that retain their source and version. Built-ins remain under release control, while custom definitions belong to one customer. This separates a common product starting point from local job design. ## What It Is Not A role definition is not a membership, an invitation or a grant. Creating Finance Clerk does not appoint anyone to that job or select a workspace. CRM responsibilities and committee appointments describe other relationships; they provide security access only when an automatic-assignment mechanism translates the relevant facts into grants. ## How It Is Used Security administrators begin with the available built-ins, then create or copy definitions when their organization needs a different combination. They select policies and rules, inspect validation feedback and save the result. Readers can inspect definitions without receiving the authority to edit them. Editing a role already held by people can affect existing access, so the definition is part of ongoing administration rather than just initial setup. Delegation checks assess widening, and administrator safeguards protect the customer's ability to manage security. Unused custom definitions can be archived while preserving their history. Referenced definitions need their dependencies resolved before archive. ## Its Facets **Permissions and catalog.** Released services supply the vocabulary of available actions, including tier, sensitivity and staff-only metadata. **Policies.** Named rule groups make access reusable across roles. Allow rules name real permissions; deny rules can also use supported patterns. **Built-in policies.** Generated application tiers and explicitly declared policies supply Rhythm's shared starting definitions, with sensitive powers separated where the catalog requires it. **Custom definitions.** Customer-owned policies and roles support local jobs. Copies preserve their relationship to the original rather than becoming editable versions of the shared built-in. **Built-in roles.** Five customer roles and three staff roles group those shared policies for their respective audiences. **Empty-role indication.** A grants-nothing label helps administrators recognize a role with no effective allow before assigning it. **Eligibility binding.** An optional workspace rule can derive grants for qualifying contacts, with a configured re-check interval. ## How It Relates Custom definitions belong to one customer and cannot borrow another customer's policies. Grants connect roles to accounts or contact subjects at an allowed scope. Staff roles apply to Rhythm HQ, while staff access uses customer-appropriate roles for work inside a workspace. The catalog links those definitions to the operations applications actually expose. ## What It Could Become The product should finish the editor support for automatic assignments and settle their subject model before accepting that milestone. Definition changes also need a clear explanation of cached authorization behavior. Release-controlled built-ins and customer customization should remain distinguishable as the catalog grows, so administrators understand which changes they own and which arrive with the product.