XOLeap - User Guide: Role-Based Access Control (RBAC)

Last Updated: January 4, 2026

---

📋 Overview

XOLeap's Role-Based Access Control (RBAC) system allows you to manage user permissions with granular control. You can assign users to predefined system roles or create custom roles with specific permissions tailored to your organization's needs.

---

🎯 Key Concepts

Roles

A role is a collection of permissions. Users are assigned one or more roles, and they inherit all permissions from their assigned roles.

Permissions

A permission is a specific action a user can perform (e.g., manage.products, view.reports, edit.orders).

System Roles

XOLeap includes five predefined system roles:

• Owner: Full access to all features
• Admin: Administrative access (can manage users and roles)
• Manager: Operational management access
• Staff: Basic operational access
• Cashier: POS-only access

Custom Roles

You can create unlimited custom roles with specific permission combinations to match your organization's workflow.

---

👥 Managing Users and Roles

Accessing Role Management

1. Navigate to Settings > Roles (or /roles)
2. You must have the manage.roles permission to access this page

Viewing Roles

The Roles page displays:

• System Roles: Predefined roles available to all organizations
• Custom Roles: Roles created specifically for your organization

Each role shows:

• Role name and description
• Number of users assigned
• List of permissions (click "View" to expand)

---

➕ Creating Custom Roles

Step 1: Create the Role

1. On the Roles page, click "Create Custom Role"
2. Fill in the role details:
   • Name: Display name (e.g., "Warehouse Supervisor")
   • Key: Unique identifier (auto-generated from name)
   • Description: Optional description of the role's purpose
3. Click "Create Role"

Step 2: Assign Permissions

1. After creating the role, you'll be taken to the role edit page
2. Select permissions from the organized categories:
   • User & Role Management
   • Analytics & Reporting
   • Inventory Management
   • Order Management
   • Returns
   • POS Operations
   • E-Commerce
   • Financial
   • Settings
   • And more...
3. Check the boxes for permissions you want to grant
4. Click "Save Permissions"

Permission Categories

Permissions are organized by feature area:

User & Role Management:

• manage.users - Manage users in organization
• manage.roles - Manage roles and permissions

Analytics & Reporting:

• view.analytics - Access analytics module
• view.reports - View reports and analytics
• export.reports - Export reports

Inventory Management:

• manage.inventory - Perform inventory operations
• manage.products - Create, edit, and delete products
• manage.locations - Manage warehouse locations
• manage.vendors - Manage vendors and suppliers
• manage.purchase_orders - Create and manage purchase orders
• receive.inventory - Receive inventory into warehouse
• adjust.inventory - Adjust inventory quantities

Order Management:

• manage.orders - Manage orders and fulfillment
• create.orders - Create new orders
• edit.orders - Edit existing orders
• cancel.orders - Cancel orders
• pick.orders - Pick orders for fulfillment
• pack.orders - Pack orders for shipment
• ship.orders - Ship orders

And many more...

---

👤 Assigning Roles to Users

Method 1: From the Users Page

1. Navigate to Settings > Users (or /users)
2. Find the user you want to assign roles to
3. Click "Edit Roles" button
4. Select one or more roles from the dropdown
5. Click "Save"

Method 2: From the Roles Page

1. Navigate to Settings > Roles
2. Find the role you want to assign
3. Click "View" to see the role details
4. The role details show all users currently assigned
5. To assign to a user, go to the Users page (see Method 1)

Multiple Roles

Users can have multiple roles. Permissions from all roles are combined (union of all permissions).

Example:

• User has "Staff" role (basic permissions)
• User also has "Reports Viewer" custom role (view.reports permission)
• User has access to all permissions from both roles

---

🔒 Permission Checks

How Permissions Work

When a user tries to access a feature:

1. System checks if user has the required permission
2. If permission exists in any of the user's roles → Access granted
3. If permission doesn't exist → Access denied with graceful error message

Graceful Error Handling

If a user doesn't have permission:

• Web requests: Redirected with a friendly error message
• AJAX requests: Error toast notification displayed
• No 403 errors: User-friendly messages instead

---

🛡️ Security Features

Organization Scoping

• Permissions are scoped to your organization
• Users from one organization cannot access another organization's data
• Custom roles are organization-specific
• System roles work across organizations but are scoped per assignment

Protection Against Privilege Escalation

• Users cannot remove their own Owner/Admin roles if they're the only admin
• Organization owners cannot downgrade their own account status
• Permission checks happen at multiple levels (middleware, controller, service)

Audit Trail

• All role assignments are logged
• Permission changes are tracked
• Complete history of who changed what and when

---

📝 Common Use Cases

Use Case 1: Warehouse Supervisor

Goal: Create a role for warehouse supervisors who can manage inventory and receive orders, but cannot manage users or billing.

Permissions to Grant:

• manage.inventory
• manage.products
• manage.locations
• receive.inventory
• adjust.inventory
• manage.purchase_orders
• view.reports

Steps:

1. Create custom role "Warehouse Supervisor"
2. Select the permissions listed above
3. Assign role to warehouse supervisor users

Use Case 2: Customer Service Representative

Goal: Create a role for customer service who can view orders and customers, create orders, and manage returns, but cannot access financial data.

Permissions to Grant:

• view.customers
• view.orders
• create.orders
• edit.orders
• manage.returns
• view.reports (read-only)

Steps:

1. Create custom role "Customer Service"
2. Select the permissions listed above
3. Assign role to customer service users

Use Case 3: Financial Analyst

Goal: Create a role for financial analysts who can view all financial data and reports, but cannot make changes.

Permissions to Grant:

• view.financial_reports
• view.reports
• export.reports
• view.analytics
• view.customer_invoices
• view.vendor_invoices

Steps:

1. Create custom role "Financial Analyst"
2. Select the permissions listed above
3. Assign role to financial analyst users

---

⚠️ Important Notes

System Roles Cannot Be Modified

• System roles (Owner, Admin, Manager, Staff, Cashier) cannot be edited
• You can only view their permissions
• To customize permissions, create a custom role

Owner Role Protection

• The first user in an organization (Owner) has special protections
• Owners cannot remove their Owner role if they're the only owner
• This prevents accidental lockout

Permission Inheritance

• Users inherit permissions from all assigned roles
• If a user has multiple roles, they get the union of all permissions
• Removing a role removes only that role's permissions (other roles' permissions remain)

---

🔍 Troubleshooting

User Cannot Access a Feature

Check:

1. Does the user have a role assigned?
2. Does that role have the required permission?
3. Is the permission correctly scoped to the organization?

Solution:

1. Go to Users page
2. Check user's assigned roles
3. Go to Roles page
4. Verify the role has the required permission
5. If not, either:
   • Add permission to the role, or
   • Assign a different role that has the permission

Permission Not Working

Check:

1. Is the permission key correct?
2. Is the role properly assigned to the user?
3. Is the organization context correct?

Solution:

1. Verify permission key matches exactly (case-sensitive)
2. Re-assign the role to the user
3. Clear browser cache and try again

Cannot Edit Own Roles

Note: This is a security feature. If you're the only Owner/Admin:

• You can edit your roles, but cannot remove Owner/Admin
• This prevents accidental lockout
• If you need to change roles, first assign another user as Owner/Admin

---

📚 Related Documentation

• User Guide: Getting Started
• User Guide: Core Features
• User Guide: Store Credit

---

Last Updated: 2026-01-04