--- id: CON-PFM-SEC-005 name: Role Grant feature: FEAT-PFM-SEC-03 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 grant assigns a role to an account or an automatic contact subject within a defined scope and optional time window. owned_by: MOD-PFM-SEC synonyms: - assignment - role assignment - access not_to_be_confused_with: - Role - Invitation - Staff access grant facets: - name: Scope meaning: 'The assignment names a customer, workspace, supported custom record or staff-platform scope.' used_for: Locating the authority represented by the role. - name: Grant state meaning: 'Pending, scheduled, live, ended and withdrawn distinguish current authority from retained history.' used_for: Explaining whether an assignment counts now. - name: Window and conditions meaning: Optional validity dates and supported conditions limit when access applies. used_for: Bounding authority by time and circumstances. - name: Automatic grant meaning: A source-managed assignment names a contact and its derivation. used_for: Keeping access aligned with appointments or eligibility. - name: Widening rule meaning: Delegation checks require authority for the access handed out and refuse self-widening. used_for: Preventing privilege escalation through administration. - name: Last administrator guard meaning: Guard checks preserve an active customer security administrator and a Rhythm Administrator. used_for: Retaining the ability to administer security. - name: Security context meaning: The evaluated document describes usable access for the current workspace. used_for: Initializing the console and explaining permissions. - name: Security history meaning: The audit trail describes security changes and recorded refusals. used_for: Supporting access reviews and investigations. relationships: - to: CON-PFM-SEC-004 statement: Each assignment identifies one role definition. provenance: test source: >- services-platform:modules/security/tests/integration/services/membership/manage-assignments.integration.spec.js#grants a role at customer scope, active at once for an active person, and audits it as widening - to: CON-PFM-SEC-003 statement: Manual assignments name accounts; automatic assignments can name contacts. provenance: test source: >- services-platform:modules/security/tests/integration/services/persistence/assignments.derived.integration.spec.js#writes an active, contact-keyed row naming its derivation, granted by the session’s actor - to: CON-PFM-SEC-002 statement: Workspace-scoped assignments apply within a workspace belonging to the customer. provenance: test source: >- services-platform:modules/security/tests/integration/services/membership/set-role-scope.integration.spec.js#turns the customer grant into one active grant per tenant asked for, revoking the customer grant - to: CON-PFM-SEC-006 statement: Staff access creates ordinary assignments for the customer work it authorizes. provenance: test source: >- services-platform:modules/security/tests/integration/services/staff-access/approved-tenant-access.integration.spec.js#materializes a tenant-scoped assignment of the role, ending when the grant does lifecycle: - state: pending meaning: 'An invitation offers the assignment, which authorizes no work yet.' how_it_changes: Acceptance activates it; withdrawing membership ends it. - state: scheduled meaning: The assignment awaits its start time and does not authorize work before then. how_it_changes: Reaching the start opens its validity window. - state: live meaning: Current evaluation can use the role within the assignment’s scope and conditions. how_it_changes: 'Granting to active membership, accepting an invitation or reaching the start makes it usable.' - state: ended meaning: 'The validity window has closed, leaving retained history.' how_it_changes: Reaching the end expires the assignment. - state: withdrawn meaning: Revocation ends the assignment while retaining its recorded history. how_it_changes: 'An administrator, membership removal or the owning derivation withdraws it.' acted_on_by: - CAP-PFM-SEC-007 - CAP-PFM-SEC-008 - CAP-PFM-SEC-010 - CAP-PFM-SEC-011 - CAP-PFM-SEC-014 - CAP-PFM-SEC-015 - CAP-PFM-SEC-017 visible_to: - ACT-PFM-001 - ACT-PFM-002 - ACT-PFM-003 - ACT-PFM-004 evidence: - >- Pinned services-platform references for the structured rows: modules/security/tests/integration/services/membership/manage-assignments.integration.spec.js; modules/security/tests/integration/services/membership/set-role-scope.integration.spec.js; modules/security/tests/integration/services/persistence/assignments.derived.integration.spec.js; modules/security/tests/integration/services/staff-access/approved-tenant-access.integration.spec.js. supersedes: [] --- # Role Grant ## What It Is This retained record is superseded by the User Account concept, which now owns its facets. A role grant applies an access definition to a subject, a scope and an optional period. It turns a reusable job description into an assignment: one person can hold a role across the customer, while another holds it only in a chosen workspace. The role definition alone establishes no person's entitlement. An ordinary assignment names an account. An automatic assignment can instead name a contact and reach the portal member linked to that person. Invitations offer grants that remain pending until acceptance, while active memberships can receive usable grants directly. Time windows can defer the start or end the assignment later. The grant remains explainable after its active period. Withdrawn and ended assignments are retained as history, and changes can be reviewed in relation to both the grant and the person. This gives administrators a record of how access develops rather than only a snapshot of today's roles. ## What It Is Not A grant differs from its role definition and from the invitation that may offer it. A CRM responsibility does not itself authorize application use. Staff access has a separate request and consent record, although its usable authority is materialized through an ordinary role assignment. Licensing and application-access checks remain additional parts of authorization. ## How It Is Used Administrators assign a role from a person's access administration, choose where it applies and revisit that scope as work changes. A role can move between customer-wide access and selected workspaces without manually coordinating every individual assignment. Grant checks allow administrators to inspect whether a proposed delegation is permitted before writing it. The access explanation connects allowed permissions to the definitions and assignments behind them. That explanation helps distinguish an absent grant from a conditional or denied permission. Automatic assignments direct administrators to change their source rather than edit the generated assignment by hand. Revocation changes stored authority immediately, but cached gateway decisions have their own expiry. ## Its Facets **Scope.** Customer, workspace, supported custom-record and staff-platform scopes determine where the definition counts. **State.** Pending, scheduled, live, ended and withdrawn distinguish eligibility for current evaluation from retained history. **Window and conditions.** Start and end times limit duration; supported conditions limit circumstances. A change to a deny can widen access even when its scope becomes smaller. **Automatic source.** Derivation metadata explains which appointment or eligibility rule owns the assignment and how it is maintained. **Delegation safeguards.** Widening checks prevent an administrator from handing out authority they cannot exercise. Last-administrator checks protect continued administration. **Security context and history.** The context supplies evaluated access to the console. The trail explains changes and refusals, with sensitive invitation and password material excluded. ## How It Relates Each role assignment names its access definition and subject. Workspace scope connects the assignment to the association where work happens. Staff access materializes the same kind of authority without changing staff membership. A portal account's linked contact connects it to contact-keyed automatic assignments. ## What It Could Become The product should resolve whether generated assignments always belong to contacts or can belong to logins. Immediate revocation across cached requests requires a mechanism beyond the current flush submission. The product should make the origin of an assignment clear during access review, so administrators can distinguish a deliberate delegation from authority maintained by an appointment or eligibility rule.