Roles & Permissions

Define and manage reusable access profiles to control exactly what your team members can see and do within your organization.

What are Roles & Permissions?

Instead of configuring access individually for every employee, Orbit Resolve uses a role-based access control (RBAC) system. This means you grant access to a job profile rather than an individual person.

To understand this system, you need to understand the difference between four key concepts:

• User: A real person logging into the platform (e.g., Sarah). A user is who is performing the action.
• Permission: A specific, highly granular action someone is allowed to perform (e.g., "View Invoices", "Create Tasks", or "Delete Projects"). Permissions are the exact rules that unlock features.
• Role: A reusable profile that bundles multiple permissions together (e.g., "Finance Team" or "Project Manager"). A role represents a job function.
• Module: A broad functional area of the application (e.g., Expense Management, Orbit Pulse, Settings) that those permissions govern.
• Member: A user who has been officially assigned to a specific role.

When you assign a user to a Role, they become a Member of that role. They automatically inherit all the permissions bundled inside it. If you update the role later (for example, by adding a new permission), everyone assigned to it instantly gets that updated access.

The Mental Model

Before configuring access, it helps to visualize how the pieces fit together.

Organization → Users → Assigned Roles → Permissions → Allowed Features

For a realistic example, consider a new employee named Sarah:

1. User: Sarah is hired and invited to the platform.
2. Role: Her manager assigns her the Finance Team role.
3. Permissions: The Finance Team role has been configured to contain the View Expenses, Approve Expenses, and View Budget permissions.
4. Result: Because Sarah has this role, the Orbit Resolve platform allows her to see the Expense Management module and approve pending reports. If she tries to access the Marketing CRM, she will be denied, because her role lacks those permissions.

Why would I use this?

Why do permissions exist, and why would an organization create multiple roles?

Without roles, administrators would need to manage access individually for every single employee. If you hired 50 people, you would have to click 50 checkboxes for every single one of them.

Roles allow organizations to define access once and reuse it infinitely. You create multiple roles because different departments need different tools to do their jobs securely.

For example:

• Finance employees need access to budgets and expenses, but shouldn't be able to change the organization's name.
• Marketing employees need access to the CRM (Orbit Pulse) but shouldn't see confidential financial reports.
• Orbit Papers viewers only need read-access to corporate documents.
• Organization administrators need full access to configure the entire platform.

By creating a specific role for each of these groups, you ensure that your data is secure and that your employees' screens aren't cluttered with features they don't know how to use.

How access control works

---

Before you begin

Before you can effectively manage roles, ensure you understand the following prerequisites:

• Required Access: You must be an Organization Administrator or have a custom role that includes both the org.roles.view and org.roles.create / org.roles.edit permissions. Without these, the Roles & Permissions tab will be hidden or read-only.
• Enabled Modules: The list of available permissions you can select is generated dynamically based on the modules (packages) currently active for your organization. If you recently purchased and enabled a new module package, new permissions will automatically appear in your list.
• Where Users are Assigned: You cannot assign users to roles directly from the Roles & Permissions page. This page defines what the roles are. You define who gets them in User Role Mapping (under Access Management).

Navigation: Organization Settings → Roles & Permissions

Application URL:
https://agiledigest.dev-orbit.com/org/roles

---

At a glance

Feature	Details
Location	Organization Settings → Roles & Permissions
Purpose	Create and configure reusable permission sets (Roles).
Who manages it	Organization Administrators
Can create roles?	Yes
Can edit roles?	Yes (Except protected Administrator/Owner system roles)
Can delete roles?	Yes (Except protected system roles, and roles currently assigned to active users)
Can use templates?	Yes (Templates automatically group common permissions based on your active modules)
Can assign permissions?	Yes
Where are users assigned?	User Role Mapping (Access Management page)
Special Owner behavior	The Administrator/Owner role cannot be edited or deleted, as it bypasses all permission checks to ensure you never lose access to your organization.

---

Understanding the Roles & Permissions page

The main Roles & Permissions dashboard provides a complete overview of every access profile in your organization.

📸 Screenshot placeholder: roles-permissions-main-page

Capture: Roles & Permissions heading, Use Template & Create Role buttons, Role cards (Owner, custom roles), Admin Access badges, Member counts on cards.

Suggested caption: The Roles & Permissions dashboard showing standard and custom access profiles.

Role Cards

Each card on this screen represents a single role. The card displays critical information at a glance:

• Role Name & Description: The display name of the role (e.g., "Creative Team") and a brief explanation of what it is used for.
• Admin Access Badge: If a role is a protected system role with full bypass privileges (meaning it ignores all normal permission rules and can do anything), it will have a prominent Admin Access badge.
• Members Count: The exact number of users currently assigned to this role (e.g., 5 Members). This number is calculated live.
  • What happens when a role has zero members? If it says 0 Members, nobody currently has this role. The role simply sits dormant. You can safely edit or delete dormant roles without affecting any active employees.
• Actions Menu: When you hover your mouse over a custom role card, a menu appears allowing you to Edit, Duplicate, or Delete the role. (System roles will hide the delete button).

---

Creating a Role

There are two primary ways to create a role: using a pre-configured template (fast and safe), or building a custom role from scratch (highly granular).

Option 1: Use a Template (Recommended)

Templates provide ready-made roles based on the module packages your organization has purchased. This is the safest way to ensure a user gets exactly the permissions they need for a specific tool.

1. Click Use Template in the top right corner. The template drawer will open on the right side of your screen.
2. Browse the templates, which are grouped by package (e.g., Full Access, Day-to-day, Read-only).
3. Select one or more templates. You can combine multiple templates into a single role. For example, you can select the "Finance Day-to-Day" template and the "CRM Read-Only" template simultaneously.
4. The system will automatically calculate the total number of permissions granted at the bottom of the drawer.
5. Enter a Role Name and Description. (If you select a single template, the system will autofill these for you).
6. Click Create Role.

Expected Result: The new role is created instantly. The system will immediately open the newly created role in the standard Edit screen, allowing you to review the exact permissions that were applied and fine-tune them if necessary.

Option 2: Create Custom Role

If templates don't fit your exact needs, you can hand-pick every individual permission.

1. Click Create Role. The Create Role drawer will open.
2. Enter a clear Role Name (e.g., Marketing Contractor).
3. Enter a short Description to help other administrators understand its purpose in the future.
4. In the Access Controls section, you will see a list of every module available in your organization. Click the arrow next to a module category to expand it.
5. Check the specific permissions you want to grant.
   • Tip: Use the Search bar to quickly find specific capabilities (e.g., search the word "delete" to find and verify all deletion permissions across the entire platform).
   • Tip: You can use the "Select All" button on a module to instantly grant all permissions within that specific area.
6. Click Save Role.

📸 Screenshot placeholder: roles-permissions-create-role

Action: Select Create Role.

Capture: Page heading, Role Name and Description fields, Access Controls search bar and category dropdown, Expanded permission module showing checkboxes, Save/Cancel actions.

Suggested caption: Creating a custom organization role and selecting specific permissions.

Expected Result: The drawer closes, a success notification appears, and the new role appears on your main dashboard as a card. It is now ready to be assigned to users in the Access Management screen.

---

Modifying a Role

You can edit a custom role at any time as your organization's needs evolve.

1. Hover over the role card on the main dashboard.
2. Click the Edit (pencil) icon.
3. The Edit drawer will open. Add or remove permissions using the checkboxes.
4. Click Save Role.

What happens when permissions are changed? Changes are applied universally and instantly.

• If you add a permission, every user currently assigned to that role will immediately gain that capability.
• If you remove a permission, every user currently assigned to that role will instantly lose that capability. Related menu items, buttons, and pages will disappear from their screen the next time they refresh.

The Administrator / Owner Role (System Roles)

You will notice an Admin Access role (often called Owner or Organization Admin). When you attempt to edit this role, you will see a warning message and the permissions matrix will be locked and grayed out.

info

What does "Admin Access" mean? This role automatically bypasses all permission checks to guarantee full, unrestricted access to the entire organization. Because it has universal access, you cannot modify its individual checkboxes, and you cannot delete it. This is a deliberate safety mechanism to ensure you never accidentally lock yourself out of your own organization. You can, however, change its name and description.

---

Duplicating a Role

If you need to create a role that is very similar to an existing one (for example, creating a Finance Manager role that is identical to Finance Assistant but with three extra approval permissions), you can duplicate it to save time.

1. Hover over the source role on the dashboard.
2. Click the Duplicate (copy) icon.
3. The system creates a direct copy of all permissions and immediately opens the new role in the Edit drawer.
4. Rename the copy (e.g., "Finance Manager") and adjust the specific permissions as needed.
5. Click Save Role.

---

Deleting a Role

If a role is obsolete, you can permanently remove it.

1. Hover over the custom role and click the Delete (trash) icon.
2. A confirmation modal will appear. Click to confirm the deletion.

warning

Deletion Safeguard You cannot delete a role if it is currently assigned to users (if its member count is greater than zero). If you attempt to delete an active role, the system will block the action and display a warning telling you exactly how many users are attached. You must navigate to User Role Mapping and reassign those users to a different role before the system will allow you to delete this one.

---

Troubleshooting

Problem	Likely reason	What to check
I can't edit the permissions on my Administrator role.	It's a protected system role with universal access.	This is intentional design. System roles bypass permission checks entirely and are locked to prevent accidental lockouts.
I removed a permission from a role, but a user still has access to the feature.	The user might be an Organization Owner, a Super Admin, or they might be assigned to a completely different role than you think.	Navigate to User Role Mapping and verify exactly which role the user is assigned to. Also verify if they have Owner status.
I can't delete a custom role.	The role is still assigned to active members.	Look at the "Members" count on the role card. If it is 1 or higher, navigate to User Role Mapping and reassign those users to a different role first.
I don't see permissions for a specific feature I want to grant.	Your organization hasn't enabled that module package yet, or you are filtering by the wrong category.	Check your active packages. If the package is active, use the "All Categories" filter and the Search bar to find the exact wording.

---

Glossary

For quick reference, here are the terms used throughout this documentation:

Term	Meaning
Role	A reusable access profile that bundles multiple permissions together (e.g., "Marketing Team").
Permission	A specific, individual capability checked by the system (e.g., org.users.view).
Member	A real user who has been assigned to a role.
Module	A functional area of the application (e.g., Expense Management, Settings).
User Role Mapping	The process and interface used to assign Users to Roles.

---

Next steps

Now that you have defined what your roles are, the next step is to assign your team members to them.

• Assign users to roles in User Role Mapping (Navigate to Organization Settings → Access Management)
• Learn how technical permission codes are structured

---

Technical / Implementation Notes

This section is for developers and QA engineers maintaining the Orbit Resolve frontend.

• Route: /org/roles
• Main Component: /src/routes/org/OrgRoles.tsx
• Data Models: Role, Permission, ModulePermissions, RoleTemplate, TemplatePackageGroup
• APIs Used:
  • GET /org/roles: Lists all roles. This endpoint returns the user_count field used for the member count display and deletion validation.
  • GET /org/roles/matrix: Fetches the live permission registry, grouped by category and module.
  • GET /org/roles/permissions?id={id}: Fetches the currently assigned permissions for a specific role during editing.
  • GET /org/roles/templates: Fetches predefined templates from backend packages. The frontend groups these by package_id.
  • POST /org/roles/from-template: Generates a role from an array of combined template IDs (template_ids).
  • POST /org/roles/duplicate?id={id}: Deep copies a role entirely on the backend, returning the new role object.
  • POST /org/roles and PUT /org/roles?id={id}: Standard CRUD operations. Note that permissions are submitted in a separate payload via POST /org/roles/permissions?id={id} for existing roles.
• Validation & Enforcement Behaviors:
  • Admin Locks: Roles flagged with is_org_admin = true or is_system_role = true trigger a locked UI state in the Edit drawer. The frontend expressly skips sending POST /org/roles/permissions for these roles when saving, as the backend enforces a full bypass.
  • Deletion Blocks: Role deletion (DELETE /org/roles?id={id}) is intercepted immediately on the frontend if user_count > 0. The UI displays an informational showConfirmation modal instead of attempting the API call, gracefully preventing foreign key constraint violations and orphaned users on the backend.
• Future Maintenance:
  • If new backend packages introduce new template types, verify they render correctly in the TemplatePackageGroup mapping within OrgRoles.tsx.
  • User assignment logic is expressly handled outside this component (in OrgAccessPage.tsx at /org/access via PUT /org/users). Do not attempt to merge user assignment into OrgRoles.tsx without consulting the product spec, as the RBAC duties are intentionally separated.