Roles & Permissions

Overview

NBOX Portal uses a role-based access control (RBAC) system to manage what users can see and do within the application. This system consists of three main components:

• Permissions — Individual access rights (e.g., "can view orders", "can edit users")
• Roles — Collections of permissions grouped together (e.g., "Admin", "Staff", "Accounts")
• Users — People who are assigned roles to access the system

Understanding Roles

A role is a named collection of permissions that can be assigned to users. Each user can have one role, and that role determines what they can access in the system.

Role Properties

• Name — A unique identifier for the role (e.g., ADMIN, STAFF)
• Display Name — Human-readable name shown in the interface
• Description — Optional explanation of the role's purpose
• Permissions — List of permissions granted to users with this role

Protected Roles

Some roles are marked as protected and cannot be deleted. These are core system roles that are essential for the application to function correctly. Protected roles can still be edited to modify their permissions.

Understanding Permissions

Permissions are granular access rights that control specific actions within the application. Each permission follows a consistent naming pattern: resource:action.

Permission Structure

Common Action Types

• read — View data (e.g., orders:read)
• create — Add new records (e.g., users:create)
• update — Modify existing records
• delete — Remove records
• manage — Full control including all CRUD operations

Permission Matrix

The Permission Matrix provides a visual overview of which permissions are assigned to each role. It's the fastest way to understand and modify role-permission relationships.

Reading the Matrix

• Columns — Each column represents a role
• Rows — Each row represents a permission, grouped by resource
• Checkmarks — A checkmark indicates the role has that permission
• Empty cells — No checkmark means the role lacks that permission

Using the Matrix

If you have the settings:manage permission, you can:

• Toggle permissions — Click any cell to add or remove a permission from a role
• View role details — Hover over role headers to see user count and permission percentage
• Navigate by resource — Permissions are grouped by resource type for easy navigation

Managing Roles

Access role management from Admin > Roles & Permissions. The "Roles Overview" tab shows all available roles as cards with their details and permissions.

Creating a Role

1. Open the Role Form

• Click the "Add Role" button in the top right corner
• A slide-out panel will appear on the right side

2. Fill in Role Details

• Name — Enter a unique identifier (uppercase, no spaces, e.g., WAREHOUSE_MANAGER)
• Display Name — Enter a human-readable name (e.g., "Warehouse Manager")
• Description — Optionally describe the role's purpose

3. Assign Permissions

• Select the permissions this role should have from the permission list
• Permissions are grouped by resource for easier selection
• You can select multiple permissions by clicking each checkbox

4. Save the Role

• Click "Create Role" to save
• The new role will appear in the Roles Overview tab

Editing a Role

• Find the role card in the Roles Overview tab
• Click the "Edit" button on the role card
• Modify the role details and permissions as needed
• Click "Update Role" to save changes

Deleting a Role

• Find the role card in the Roles Overview tab
• Click the "Delete" button (only visible for non-protected roles)
• Review the confirmation dialog showing affected users
• Confirm deletion by clicking "Delete"

Managing Permissions

The "All Permissions" tab lists every permission in the system, organized by resource. Each permission shows how many roles are currently using it.

Creating a Permission

1. Open the Permission Form

• Click the "Add Permission" button

2. Fill in Permission Details

• Name — Use the format resource:action (e.g., inventory:export)
• Display Name — Human-readable name (e.g., "Export Inventory")
• Resource — The feature area (e.g., inventory)
• Action — The operation type (e.g., export)
• Description — Explain what this permission allows

3. Save the Permission

• Click "Create Permission"
• The new permission will appear in the All Permissions list and can be assigned to roles

Editing a Permission

• Find the permission in the All Permissions tab
• Click the pencil icon to edit
• Modify the permission details as needed
• Click "Update Permission" to save

User Management

Users are managed from Admin > Users. Each user can be assigned one role that determines their access level.

Creating Users

1. Open the User Form

• Navigate to Admin > Users
• Click "Add User"

2. Enter User Details

• Email — The user's email address (used for login)
• First Name and Last Name
• Password — Initial password (user can change later)

3. Assign a Role

• Select a role from the dropdown menu
• The role determines what the user can access once they log in

4. Save the User

• Click "Create User"
• The user can now log in with their email and password

Assigning Roles to Users

• Navigate to Admin > Users
• Find the user in the list and click the edit icon
• Select a new role from the role dropdown
• Click "Update User" to save

Super Admins

Super Admins are special users who bypass all permission checks and have unrestricted access to every feature in the system.

Super Admin Characteristics

• Full Access — Can access all features regardless of role
• No Permission Checks — All permission requirements are skipped
• Visible in Super Admins Tab — Listed separately in the Roles & Permissions page

Creating a Super Admin

• When creating or editing a user, select "Super Admin" from the role dropdown
• This option grants unlimited access to the user

Best Practices

Principle of Least Privilege

Grant users only the permissions they need to do their job. Start with minimal permissions and add more as needed rather than starting with full access and removing permissions.

Use Descriptive Role Names

Name roles after job functions rather than individual people. Use names like "Warehouse Staff" or "Accounts Manager" rather than "John's Role".

Regular Access Reviews

• Periodically review who has access to what
• Remove roles from users who no longer need them
• Update role permissions when job responsibilities change

Limit Super Admin Accounts

• Keep the number of Super Admins to an absolute minimum
• Consider using regular roles with broad permissions instead
• Document who has Super Admin access and why

Test Before Deploying

When creating new roles, test them by logging in as a user with that role to verify the access is correct before assigning it to production users.

Quick Reference

Navigation

Required Permissions

Tabs Overview