BriefSpec Roles and Privileges Guide

Roles and Privileges Guide

User Guide

BriefSpec

1. Introduction

Roles and Privileges control who can see and do what in BriefSpec. Every screen, button, and action is governed by a privilege assigned to a role. Understanding this system is essential for tenant administrators, project managers, and anyone responsible for secure access across your organization.

This guide explains roles, privilege levels, conditions, tenant-wide versus project-scoped access, and how to configure roles without breaking user workflows. Detailed feature key references are in the Appendix.

2. Why Roles and Privileges Matter

What privileges protect

1. Tenant data – clients, users, subscription settings, and organization-wide configuration.
2. Project workspaces – backlog, defects, test cases, plans, boards, documents, and more.
3. Administrative actions – creating roles, assigning users, resetting defaults, managing plans.

What happens when privileges are wrong

1. Users cannot see menus or buttons they need (too restrictive).
2. Users see controls they should not use (too permissive).
3. Project teams experience inconsistent access when tenant roles and project overrides conflict.

Privileges are evaluated from feature keys returned by the platform API, not from job titles hardcoded in the application.

3. Key Concepts

Role

A named collection of privileges (for example Application Admin, Project Manager, Tester, Client User). Roles can be system-provided or custom-created by your tenant.

Privilege

The access level assigned to a role for a specific feature key.

Feature key

A stable identifier such as view-backlog, add-client, or settings-role-privileges. The application uses feature keys exclusively to show, hide, or disable UI controls.

Privilege level

1. Hidden – feature and controls are not shown.
2. Read Only (Read) – user can see the feature but cannot change data or submit actions.
3. Read and Edit (ReadAndEdit) – user can fully interact with the feature.

Condition

1. All – privilege applies to all records in scope.
2. Own – privilege applies only to records the user owns, created, or is assigned to (semantics vary by module).

When permission is Hidden, condition is always All.

Scope

1. Tenant scope – organization-wide (Clients, Users, Settings, Projects list).
2. Project scope – inside a specific project (Backlog, Defects, Test Cases, etc.).

4. System Roles vs Custom Roles

System roles (built-in)

Shipped by BriefSpec and synchronized to every tenant. Identified by a link to a master role (master_role_id is set). System role names cannot be renamed or deleted in the tenant UI.

1. Tenant (internal) roles: Application Admin, Project Manager, Developer, Tester.
2. Client (external) roles: Client User, Client Reviewer, Client Tester.

Legacy names may appear in older documentation: Test Admin is now Application Admin; Author is now Developer; Client Approver is now Client Reviewer.

Custom roles

Created by your tenant under Settings > Role Privileges. Custom roles have no master role link. You can rename, delete (if unused), and fully configure privileges subject to plan limits.

Inactive roles

Roles marked inactive remain visible in the role list with an Inactive indicator but cannot be selected for privilege editing or user assignment.

5. Three Layers of Access Control

Layer 1 – Tenant role

Assigned on the Users screen when adding or editing an organization user. Defines default privileges across the tenant and baseline project access.

Layer 2 – Project role

Assigned on a project’s Users tab. Uses the same tenant role catalog but applies project-scoped privileges when the user works inside that project.

Layer 3 – Per-user project overrides

Optional exceptions for one user on one project. Opened from Project > Users > Manage role privileges (shield icon). Overrides sit on top of the project role for specific feature keys.

Effective access in a project = project role privileges, merged with any user-specific overrides. The API returns effective_privilege_level when both role_id, project_id, and user_id are supplied.

6. Accessing Role Privileges

Primary path

1. Sidebar > Settings (gear icon).
2. Settings landing page > Role Privileges card.
3. Route: /{tenant}/{user}/{id}/role-privileges.

Breadcrumb: Home > Settings > Role Privileges.

Prerequisites

1. The settings-role-privileges privilege must not be Hidden for your role.
2. If Hidden, the Role Privileges card does not appear on Settings and you cannot open the screen.

Related access points

1. Users – assign tenant role to organization users.
2. Project > Users – assign project role and open per-user override dialog.
3. Manage Plan – subscription limits affecting custom roles (separate privilege).

7. The Role Privileges Screen

The screen uses a three-panel layout: Roles (left), Modules (center), and Privileges (right).

Roles panel (left)

1. Lists all tenant roles – system and custom, active and inactive.
2. Add (+) creates a new custom role.
3. Pencil icon renames custom roles only.
4. Trash icon deletes custom roles only (when not assigned to users).

Modules panel (center)

1. Lists functional modules (Clients, Users, Backlog, Defects, etc.).
2. Modules not included in your subscription plan may be hidden from this list.

Privileges panel (right)

1. Table of features for the selected module and role.
2. Permission column: Read and Edit, Read Only, or Hidden.
3. Condition column: All or Own (disabled when Hidden).
4. Changes save immediately when you update a row.

Reset to Default

Top action resets all tenant role privileges and user overrides for the tenant back to platform master defaults. Requires confirmation. Use with caution.

8. Creating and Managing Roles

Create a new custom role

1. Click Add (+) in the Roles panel.
2. Choose Create New (empty privilege set) or Clone from Existing (copies privileges from selected role).
3. Enter Role Name and click Create.
4. New custom roles start with privileges as defined by the clone source or platform defaults.

Rename a custom role

1. Click pencil icon next to role name, edit inline, confirm save.
2. System role names cannot be changed.

Delete a custom role

1. Click trash icon; confirm deletion.
2. Blocked if users are still assigned to the role.
3. System roles cannot be deleted.

Plan limit

Subscription plan metric no_of_add_custom_roles limits how many custom roles you can create. When exceeded, creation is blocked with a contact-sales message.

9. Configuring Privileges

Steps

1. Select a role in the Roles panel.
2. Select a module in the Modules panel.
3. For each feature row, set Permission and Condition.
4. Changes persist automatically via the platform API.

System role editing

Built-in (system) roles are read-only on the privilege table unless your plan includes customize_privileges_for_system_roles. Without that plan feature, you can view system role privileges but cannot change them.

Application Admin self-protection

For the Application Admin role, the Settings > Role Privileges feature row is locked at Read and Edit / All. Administrators cannot remove their own access to role management through the UI.

Granular Role Privileges module keys

The Role Privileges module itself has feature keys: role-privileges-view, role-privileges-add-role, role-privileges-update-role, role-privileges-delete-role, role-privileges-update-permission, role-privileges-update-condition.

10. Assigning Tenant Roles to Users

Path

1. Sidebar > Users > Add User or Edit User.
2. Role dropdown lists active tenant roles.
3. Save assigns role_id to the user subscription record.

Required privileges on Users module

1. users-view – access Users screen.
2. add-users, update-users, delete-users – respective actions.
3. update-users – required to change a user’s tenant role.

Effect

After save, the user’s tenant privilege map reloads on next session or when privileges are refreshed. If you edit privileges for the role you are currently logged in as, the Role Privileges page refreshes privileges automatically.

11. Project Roles and Per-User Overrides

Assign project role

1. Open a project > Users tab.
2. Add user or change Role column to a tenant role from the dropdown.
3. Requires view-projects-users and edit-role-projects-users privileges.

Manage role privileges (overrides)

1. Click shield / Manage role privileges icon on a project user row.
2. Dialog shows project-scoped modules only.
3. Displays base (role) value, override value, and effective value per feature.
4. Save writes tenant-user-feature-overrides for that user and project.
5. Clearing an override restores the project role default.
6. Requires projects-users-manage-privileges.

When to use overrides

1. Temporary exception for one user on one project (e.g. hide delete-backlog for a client reviewer on a single engagement).
2. Prefer creating a dedicated role and cloning privileges when many users need the same pattern.

12. How the Application Enforces Privileges

UI enforcement pattern

1. Hidden or null – control is not rendered.
2. Read Only – control appears but is disabled or non-actionable.
3. Read and Edit – control is fully active.

Sidebar and Settings cards

Settings cards use settings-* feature keys. A card is hidden when its privilege is Hidden. The Settings menu itself appears when at least one settings feature is visible.

Route protection

Some routes use RoleProtectedRoute with a required feature key (for example Manage Plan). If privilege is Hidden after the map loads, the user is redirected.

Project modules

Project screens load projectPrivileges with project_id and user_id. They prefer effective_privilege_level over privilege_level. Condition Own further restricts which rows the user can act on within a module.

Important principle

Decisions use feature_key from the API only – not role name strings. Two users with different role names may have identical privileges if configured that way.

13. Privilege Levels and Conditions in Depth

Hidden

1. User does not see menu items, tabs, buttons, or routes tied to the feature.
2. Backend denies create/update/delete for that feature.

Read Only

1. User can navigate and view data.
2. Add, Edit, Delete, Import, and similar actions are disabled.
3. Useful for auditors, client reviewers who must see but not change records.

Read and Edit

1. Full interaction including create, update, delete where the module supports it.

Condition: All

Privilege applies to every record the user can access in that module and scope.

Condition: Own

Privilege applies only to records the user created, owns, or is assigned to. Used on features such as own-projects-projects, and enforced in Plan, Boards, Documents, Service Requests, and Backlog modules. Even with Read and Edit, the user cannot act on others’ records when condition is Own.

14. Plan and Subscription Limits

no_of_add_custom_roles

1. Maximum custom tenant roles you can create.
2. Typical tiers: Free 0, Professional 5, Business 10, Enterprise 20 (confirm on your plan).

customize_privileges_for_system_roles

1. When enabled, allows editing privileges on built-in system roles.
2. When disabled, system role privilege tables are view-only.

Module entitlements

Plan module_* keys (module_plan, module_backlog, module_boards, etc.) hide modules from the Role Privileges module list when not subscribed.

Other plan interactions

1. test_case_library_module – Testcase Library settings card.
2. configure_own_openai_key – OpenAI Key settings card.

Role Privileges page refreshes plan utilization after create/delete role.

15. Built-in Protections and Restrictions

1. System roles: no rename, no delete.
2. Custom roles with assigned users: cannot delete until users reassigned.
3. Application Admin: cannot remove own Role Privileges access via UI lock.
4. Hidden permission forces condition All on save.
5. Inactive roles: not selectable for editing or assignment.
6. Business rules beyond RBAC still apply (e.g. cannot delete client with active projects).
7. Reset to Default affects entire tenant privilege matrix and user overrides.

16. Common Workflows

Define a new delivery role

1. Clone from Project Manager or similar system role.
2. Adjust project module privileges (Backlog, Defects, Test Cases).
3. Assign tenant role on Users screen or project role on Project Users tab.

Give read-only portfolio access

1. Set view-* features to Read Only or Read and Edit with condition All.
2. Set add-*, edit-*, delete-* features to Hidden or Read Only.

Restrict one user on one project

1. Project > Users > Manage role privileges > override specific features to Hidden or Read Only.

Recover from misconfiguration

1. Reset to Default (tenant-wide) or clone a known-good role and reassign users.

17. Troubleshooting

1. Role Privileges card missing – settings-role-privileges is Hidden for your role.
2. Cannot edit system role privileges – plan lacks customize_privileges_for_system_roles.
3. Cannot add role – no_of_add_custom_roles limit reached.
4. User sees button but it is disabled – privilege is Read Only, not Read and Edit.
5. User cannot see expected menu – feature is Hidden or module not on plan.
6. Project access differs from tenant access – check project role and user overrides.
7. Changes not visible – user may need to refresh; privilege map loads once per session unless refreshed.

See Appendix D for an expanded message glossary.

18. Recommended Practices

1. Use descriptive custom role names (e.g. ACME Delivery Lead, Read-Only Auditor).
2. Clone from the closest system role rather than starting from empty defaults.
3. Prefer role changes over per-user overrides when the pattern applies to many users.
4. Document your tenant’s custom roles and who should receive them.
5. Test a new role with a pilot user before wide assignment.
6. Avoid Reset to Default unless you intend to wipe all tenant privilege customizations.
7. Review plan limits before designing a large role library.
8. Coordinate with project managers when changing project-scoped privileges mid-engagement.

Appendix

The following appendices provide detailed reference material for Roles and Privileges. Each section identifies its target audience so you can find content relevant to your role.

Appendix A: Quick-Reference Tables

A.1 System Roles Catalog

Target audience: Tenant administrators and security owners defining who receives which built-in role.

Tenant (internal) system roles

1. Application Admin – full tenant administration including Settings and Role Privileges.
2. Project Manager – delivery and project leadership (privileges configured by platform defaults).
3. Developer – authoring and development workflows (formerly Author).
4. Tester – test execution and related project access (merged from legacy Test Manager where applicable).

Client (external) system roles

1. Client User – external participant with client-scoped access.
2. Client Reviewer – review and approval workflows (formerly Client Approver).
3. Client Tester – client-side test execution access.

Exact default privileges per role are platform-seeded and may be customized when your plan allows editing system roles.

A.2 Privilege Level and Condition Matrix

Target audience: All administrators configuring roles; support staff explaining UI behavior.

Permission levels

1. Hidden – UI hidden; API denies mutating actions.
2. Read Only – UI visible, actions disabled.
3. Read and Edit – UI fully enabled.

Conditions (when not Hidden)

1. All – all records in scope.
2. Own – only records user owns, created, or is assigned to.

UI mapping

1. canView(featureKey) = level is not Hidden and not null.
2. canEdit(featureKey) = level is exactly ReadAndEdit.

A.3 Role Privileges Screen Feature Keys

Target audience: Administrators delegating role-management tasks without granting full Application Admin access.

1. role-privileges-view – open Role Privileges screen.
2. role-privileges-add-role – create custom roles.
3. role-privileges-update-role – rename custom roles.
4. role-privileges-delete-role – delete custom roles.
5. role-privileges-update-permission – change Permission column.
6. role-privileges-update-condition – change Condition column.

A.4 Settings Card Feature Keys

Target audience: Tenant administrators controlling who sees which Settings areas.

1. settings-role-privileges – Role Privileges card and screen.
2. settings-software-management – Software Management.
3. settings-industry-management – Industry Management.
4. settings-testcase-library – Testcase Library.
5. settings-project-template – Project Templates.
6. settings-project-settings – Project Settings.
7. settings-manage-subscription-plan – Manage Plan.
8. settings-miscellaneous – Miscellaneous reference data.
9. settings-openai-key – OpenAI Key.
10. settings-logo-changes – Logo Changes.

A.5 Tenant Scope Module Summary

Target audience: Administrators configuring organization-wide access.

Tenant-scoped modules control Clients, Users, Settings, Projects, Projects Users, Software Management, and related administration.

1. Clients (9 features)
2. Users (6 features)
3. Settings (9 features)
4. Projects (8 features)
5. Projects Users (4 features)
6. Test 1 (4 features)
7. Reports (4 features)
8. Software Management (4 features)
9. Pillars Management (8 features)
10. Industry Management (4 features)
11. Test Case Library (3 features)
12. Role Privileges (6 features)
13. Miscellaneous (27 features)
14. Project Template (4 features)
15. Logo Changes (4 features)
16. OpenAI Key (3 features)

A.6 Project Scope Module Summary

Target audience: Project managers and delivery leads configuring in-project access.

Project-scoped modules apply when a user works inside a project. Assignment uses project role plus optional overrides.

1. Dashboard (1 features)
2. Backlog (15 features)
3. Phase (7 features)
4. Phase Requirement (7 features)
5. Test Cases (14 features)
6. Test Cycles (6 features)
7. Tester Test case list Screen (5 features)
8. Test Case Execution Screen (5 features)
9. Defects (12 features)
10. Action Items (8 features)
11. Scribe360 (7 features)
12. Traceability (1 features)

Appendix B: Tenant Feature Key Reference

B.1 Clients and Users

Target audience: Client administrators and user administrators.

Clients

1. view-client – View Client
2. add-client – Add Client
3. update-client – Update Client
4. delete-client – Delete Client
5. import-clients – Import
6. export-clients – Export
7. add-client-users – Add Client Users
8. edit-client-user – Edit Client User
9. delete-client-user – Delete Client user

Users

1. add-users – Add
2. update-users – Update
3. delete-users – Delete
4. import-users – Import
5. export-users – Export
6. users-view – View

B.2 Projects and Projects Users

Target audience: Project portfolio managers and project administrators.

Projects

1. view-projects – View
2. add-projects – Add
3. update-projects – Update
4. delete-projects – Delete
5. reset-projects – Reset
6. make-active-projects – Make Active
7. own-projects-projects – Own Projects
8. start-project-projects – Start Project

Projects Users

1. view-projects-users – View
2. add-projects-users – Add
3. edit-role-projects-users – Edit Role
4. change-status-projects-users – Change Status

B.3 Settings, Role Privileges, and Administration

Target audience: Tenant administrators and platform configurators.

Settings

1. settings-logo-changes – Logo Changes
2. settings-software-management – Software Management
3. settings-industry-management – Industry Management
4. settings-testcase-library – Testcase Library
5. settings-role-privileges – Role Privileges
6. settings-miscellaneous – Miscellaneous
7. settings-project-template – Project Template
8. settings-project-settings – Project Settings
9. settings-openai-key – OpenAI Key

Software Management

1. software-management-add – Add
2. software-management-update – Update
3. software-management-delete – Delete
4. software-management-view – View

Pillars Management

1. pillars-management-add – Add
2. pillars-management-update – Update
3. pillars-management-delete – Delete
4. pillars-management-view – View
5. pillars-management-add-module – Add Module
6. pillars-management-update-module – Update Module
7. pillars-management-delete-module – Delete Module
8. pillars-management-view-module – View Module

Industry Management

1. industry-management-add – Add
2. industry-management-update – Update
3. industry-management-delete – Delete
4. industry-management-view – View

Role Privileges

1. role-privileges-view – View
2. role-privileges-add-role – Add Role
3. role-privileges-update-role – Update Role
4. role-privileges-delete-role – Delete Role
5. role-privileges-update-permission – Update Permission
6. role-privileges-update-condition – Update Condition

B.4 Libraries, Templates, and Configuration

Target audience: Template owners, library administrators, and branding administrators.

Test Case Library

1. test-case-library-view – View
2. test-case-library-create-master-testcase – Create Master Testcase
3. test-case-library-import-test-case-set – Import Test case set

Miscellaneous

1. miscellaneous-view-department – View Department
2. miscellaneous-add-department – Add Department
3. miscellaneous-update-department – Update Department
4. miscellaneous-delete-department – Delete Department
5. miscellaneous-add-location – Add Location
6. miscellaneous-update-location – Update Location
7. miscellaneous-delete-location – Delete Location
8. miscellaneous-view-location – View Location
9. miscellaneous-add-currency – Add Currency
10. miscellaneous-update-currency – Update Currency
11. miscellaneous-view-currency – View Currency
12. miscellaneous-delete-currency – Delete Currency
13. miscellaneous-add-company-size – Add Company Size
14. miscellaneous-update-company-size – Update Company Size
15. miscellaneous-view-company-size – View Company Size
16. miscellaneous-delete-company-size – Delete Company Size
17. miscellaneous-add-project-type – Add Project Type
18. miscellaneous-update-project-type – Update Project Type
19. miscellaneous-delete-project-type – Delete Project Type
20. miscellaneous-view-project-type – View Project Type
21. miscellaneous-add-solution-type – Add Solution Type
22. miscellaneous-update-solution-type – Update Solution Type
23. miscellaneous-delete-solution-type – Delete Solution Type
24. miscellaneous-add-revenue – Add Revenue
25. miscellaneous-update-revenue – Update Revenue
26. miscellaneous-delete-revenue – Delete Revenue
27. miscellaneous-view-revenue – View Revenue

Project Template

1. project-template-view – View
2. project-template-add – Add
3. project-template-delete – Delete
4. project-template-update – Update

Logo Changes

1. logo-changes-view – View
2. logo-changes-add – Add
3. logo-changes-delete – Delete
4. logo-changes-update – Update

OpenAI Key

1. openai-key-view – View
2. openai-key-add – Add
3. openai-key-update – Update

B.5 Reports and Test Modules

Target audience: Reporting administrators (module availability varies by tenant).

Test 1

1. test-1-add – Add 1
2. test-1-view – View
3. test-1-update – Update
4. test-1-delete – Delete

Reports

1. reports-add – Add
2. reports-view – View
3. reports-update – Update
4. reports-delete – Delete

Appendix C: Project Feature Key Reference

C.1 Dashboard, Backlog, and Phases

Target audience: Business analysts, phase leads, and backlog owners.

Dashboard

1. view-analytics-dashboard – View

Backlog

1. view-backlog – View
2. add-from-sow – Add from SOW
3. create-from-transcript – Create from transcript
4. create-from-import – Create from import
5. create-from-manual – Create From manual
6. update-backlog – Update
7. delete-backlog – Delete
8. export-backlog – Export
9. assign-for-review – Assign for Review
10. approve-reject – Approve/Reject
11. smart-merge – Smart Merge
12. regenerate – Regenerate
13. comments-backlog – Comments
14. attachment-backlog – Attachment
15. activity-backlog – Activity

Phase

1. add-phase – Add
2. update-phase – Update
3. delete-phase – Delete
4. executive-summary – Executive Summary
5. swimlane-view – Swimlane View
6. view-phase – View
7. start-phase – Start Phase

Phase Requirement

1. add-phase-requirement – Add
2. update-phase-requirement – Update
3. delete-phase-requirement – Delete
4. assign-for-review-phase-requirement – Assign for Review
5. approve-reject-phase-requirement – Approve/Reject
6. generate-test-cases – Generate Test cases
7. view-phase-requirement – View

C.2 Testing Modules

Target audience: Test managers, testers, and QA leads.

Test Cases

1. view-test-cases – View
2. add-test-cases – Add
3. edit-test-cases – Edit
4. import-test-cases – Import
5. export-test-cases – Export
6. delete-test-cases – Delete
7. clone-test-cases – Clone
8. link-de-link – Link/De-link
9. regenerate-test-cases – Regenerate
10. comments-test-cases – Comments
11. attachment-test-cases – Attachment
12. activity-test-cases – Activity
13. test-cases-create-with-ai – Create With AI
14. test-cases-create-manually – Create Manually

Test Cycles

1. view-test-cycles – View
2. add-test-cycles – Add
3. delete-test-cycles – Delete
4. edit-test-cycles – Edit
5. create-client-testers – Create Client Testers
6. testers-execution-list – Testers Execution List

Tester Test case list Screen

1. resume-tester-test-case-list-screen – Resume
2. start-tester-test-case-list-screen – Start
3. restart-tester-test-case-list-screen – Restart
4. view-linked-defects – View Linked Defects
5. assign-reassign-testers – Assign/Reassign Testers

Test Case Execution Screen

1. save-progress – Save Progress
2. add-feedback – Add feedback
3. add-attestation – Add Attestation
4. create-defect – Create Defect
5. download-instruction – Download Instruction

C.3 Defects, Action Items, and Traceability

Target audience: Defect managers, action item owners, and traceability users.

Defects

view-defects – View

add-defects – Create Manually

edit-defects – Edit

assign-user – Assign User

import-defects – Import

download-defects – Download

delete-defects – Delete

comments-defects – Comments

attachment-defects – Attachment

activity-defects – Activity

defects-create-with-ai – Create With AI

defects-regenerate-with-ai – Regenerate With AI

Action Items

view-action-items – View

add-action-items – Add

edit-action-items – Edit

delete-action-items – Delete

assign-user-action-items – Assign User

comments-action-items – Comments

attachment-action-items – Attachment

activity-action-items – Activity

Scribe360

view-scribe360 – View

add-scribe360 – Add

edit-scribe360 – Edit

delete-scribe360 – Delete

scribe360-add-article-style – Add Article Style

scribe360-add-job-aid-style – Add Job Aid Style

scribe360-add-short-instructions – Add Short Instructions

Traceability

view-traceability – View

C.4 Additional Project Modules (platform catalog)

Target audience: Administrators on tenants with extended module subscriptions.

These modules may appear in Role Privileges when enabled on your plan. Feature keys are defined in the platform master catalog:

Plan

plan-view, plan-add, plan-update, plan-delete, plan-import, plan-export, plan-comments, plan-activity, plan-attachments, plan-add-sub-task, plan-create-plan-from-sow, plan-create-phase-from-plan, plan-view-leave-calendar, plan-edit-leave-calendar.

Boards

board-view, board-add, board-update, board-delete, board-view-list, board-add-edit-list, board-delete-list, board-add-edit-card, board-delete-card, board-view-card-details, board-cards-comments, board-cards-attachments.

Documents

documents-view, documents-add, documents-update, documents-delete, documents-download, documents-activity.

Service Requests

service-requests-view, service-requests-add, service-requests-update, service-requests-delete, service-requests-assign-user, service-requests-comments, service-requests-attachments, service-requests-activity, service-requests-time-entry, service-requests-import, service-requests-download, service-requests-create-with-ai, service-requests-regenerate-with-ai, service-requests-resolution.

Key Decisions

view-key-decisions, add-key-decisions, update-key-decisions, delete-key-decisions, key-decision-comments, key-decision-activity, key-decision-assigne.

RAID Logs

raid-logs-view, raid-logs-add, raid-logs-update, raid-logs-delete, raid-logs-comments, raid-logs-activity.

C.5 Privilege Keys for Project User Management

Target audience: Project administrators assigning users and overrides.

view-projects-users – view Project Users tab.

add-projects-users – add user to project.

edit-role-projects-users – change project role dropdown.

change-status-projects-users – activate/deactivate user on project.

projects-users-manage-privileges – open Manage role privileges override dialog.

Appendix D: Workflows, Limits, and Troubleshooting

D.1 Scenario Playbooks

Target audience: Tenant administrators and project managers executing common RBAC tasks.

Playbook 1: Onboard a new organization role

1. Settings > Role Privileges > Add role > Clone from closest system role.

2. Adjust tenant and project module privileges.

3. Assign on Users (tenant-wide) or Project Users (project-specific).

4. Pilot with one user; expand after validation.

Playbook 2: Read-only auditor

1. Clone Application Admin or Project Manager.

2. Set all add/edit/delete/import keys to Hidden or Read Only.

3. Keep view-* keys at Read and Edit or Read Only as needed.

Playbook 3: Single-project exception

1. Keep tenant role unchanged.

2. Project > Users > Manage role privileges.

3. Override specific features; document reason and expiry.

Playbook 4: Recover from misconfiguration

1. Clone a known-good role and reassign users, OR

2. Reset to Default (tenant-wide – destructive to customizations).

D.2 Pre-Assignment Checklist

Target audience: Administrators before assigning a new or changed role to production users.

Role name and purpose documented.

Tenant vs project assignment path confirmed.

Critical Hidden keys verified (delete-*, settings-*, role-privileges-*).

Own vs All conditions reviewed for portfolio-scoped features.

Pilot user tested on representative project.

Plan limits not exceeded (custom role count).

Stakeholders notified if reducing access mid-engagement.

D.3 Plan Limits Glossary

Target audience: Tenant administrators and subscription owners.

no_of_add_custom_roles – caps custom role creation.

customize_privileges_for_system_roles – enables editing built-in role privilege matrices.

module_* plan keys – hide modules from Role Privileges module list when not subscribed.

D.4 Error and Message Glossary

Target audience: All users and support staff diagnosing access issues.

Role Privileges card not visible – settings-role-privileges is Hidden.

Cannot add role / plan limit – no_of_add_custom_roles exceeded.

System role privileges read-only – customize_privileges_for_system_roles not on plan.

Cannot delete role – users still assigned or role is system-built-in.

Button visible but disabled – privilege is Read Only, not Read and Edit.

404 on protected route – required feature key is Hidden.

User lacks project action – check project role, overrides, and Own condition.

Reset to Default confirmation – warns that tenant overrides will be lost.

Appendix E: Access Model and Terminology

E.1 Effective Privilege Resolution Order

Target audience: Technical administrators and support engineers explaining why effective access differs from role defaults.

Inside a project

1. Resolve user’s project role (TenantUserRole with project, else tenant-wide role).

2. Load RoleFeaturePrivilege – project row if present, else tenant row.

3. Apply UserFeaturePrivilegeOverride for that user + project + feature.

4. Evaluate condition (All vs Own) in module-specific rules.

5. UI uses effective_privilege_level when provided by API.

Tenant-wide (no project context)

1. Resolve role from user subscription role_name or tenant-wide TenantUserRole.

2. Load tenant-level RoleFeaturePrivilege (project is null).

3. Return privilege_level and condition for feature key.

E.2 Legacy Role Name Mapping

Target audience: Administrators migrating documentation or comparing to older BriefSpec releases.

Test Admin / TestAdmin -> Application Admin / ApplicationAdmin

Author -> Developer

Test Manager -> Tester (merged)

Client Approver -> Client Reviewer

sSupport Representative -> Tester (removed)

User records and subscriptions may still store canonical names; the UI displays friendly labels.

E.3 Sample Role Configurations (Illustrative)

Target audience: Tenant administrators designing Role Privileges. Examples only – adjust to your organization.

Application Admin (system)

Broad Read and Edit on tenant and project modules; full Settings access.

Read-Only Portfolio Viewer (custom)

view-client, view-projects, view-backlog: Read and Edit or Read Only; all mutate keys Hidden.

Project Manager (system)

Strong project module access; limited Settings; typically no Role Privileges management.

Client Reviewer (system)

Backlog/phase review features; limited delete; client-appropriate visibility.

E.4 Glossary

Target audience: All readers new to BriefSpec RBAC terminology.

Feature key – stable permission identifier (e.g. view-defects).

Privilege level – Hidden, Read, or ReadAndEdit.

Condition – All or Own scope qualifier.

Tenant role – organization-wide role on Users screen.

Project role – same role catalog applied on Project Users tab.

Override – per-user, per-project exception to project role.

System role – built-in role linked to master_role_id.

Custom role – tenant-created role with master_role_id null.

Master catalog – platform-wide default roles and features (not edited in tenant UI).

Effective privilege – final level after overrides merged.

Appendix F: Advanced Reference

F.1 Cognito Groups vs Tenant Roles

Target audience: Platform operators and senior administrators understanding authentication vs authorization.

BriefSpec uses two related layers. Cognito UserGroups provide coarse API gatekeeping at login. Tenant roles and feature privileges provide fine-grained screen and action control.

At login, the platform resolves the user’s role from subscription role_name, TenantUserRole, then Cognito groups.

Custom tenant roles work through TenantUserRole even when not named in hardcoded Cognito group lists.

Document end-user access from feature privileges, not from Cognito group name alone.

F.2 Own Condition Semantics by Area

Target audience: Project managers configuring Own condition; support explaining partial access.

Projects – own-projects-projects limits visibility to user’s projects when configured.

Backlog – ownership uses creator/assignee/reviewer rules in module helpers.

Plan – task ownership determines edit rights when condition is Own.

Boards – card/list ownership determines mutate access.

Documents – document ownership and project membership apply.

Service Requests – assignee and creator rules apply.

When in doubt, pilot Own condition with a test user on a real project record.

F.3 Related Settings Cross-Reference

Target audience: Administrators navigating adjacent configuration screens.

Settings > Role Privileges – this guide.

Settings > Manage Plan – subscription limits affecting roles.

Users – tenant role assignment.

Project > Users – project role and overrides.

Settings > Project Templates – separate from roles; controls module layout not user access.

Settings > Miscellaneous – reference data privileges under miscellaneous-* keys.

F.4 Platform-Only Operations (Not in Tenant UI)

Target audience: BriefSpec platform operators; tenant admins setting expectations.

Create or delete master roles in master catalog.

Bulk seed privilege matrix via platform Excel upload.

sync-master-access-all-tenants – push master defaults to all tenants.

Reset affects tenant data only; master catalog changes are platform-operated.