👥 Users & Roles

Manage your team with role-based access control (RBAC), default roles, custom roles, and granular permissions.

Role-Based Access Control (RBAC)

Deliverty Hub uses a robust RBAC system to control what each user can see and do. Every user is assigned a role, and each role contains a set of permissions. The platform evaluates permissions at both the API level (backend guards) and the UI level (the <PermissionGate> component).

How Permissions Work

Permissions are enforced at two layers: the backend uses @Roles() and @Permissions() decorators on API endpoints, while the dashboard uses the <PermissionGate> component to conditionally render UI elements. Both layers check the same permission set from the user's role.

Default Roles

Deliverty Hub ships with two built-in roles that cannot be deleted. These roles provide the foundation for access control across the platform.

Role Scope Description
Super Admin Global (all organizations) Full platform access. Can create and manage organizations, view all tenants, and perform system-level operations. Implicitly has all permissions — no explicit permission grants are needed. This role bypasses organization scoping entirely.
Organization Admin Single organization Full access within their organization. Can manage users, roles, tasks, agents, settings, and all resources scoped to their organization. Cannot access other organizations or system-level features.
Super Admin Access

The Super Admin role has unrestricted access to the entire platform, including all organizations. Assign this role only to trusted platform operators. Super Admin users bypass all organization-level data isolation.

Creating Custom Roles

Beyond the default roles, you can create custom roles tailored to your organization's structure. Custom roles let you define exactly which actions a user can perform.

How to Create a Custom Role

1

Navigate to Settings → Roles

Open the organization settings page and select the "Roles" tab to view existing roles.

2

Click "Create Role"

Provide a name for the role (e.g., "Dispatcher", "Viewer", "Finance Manager") and an optional description.

3

Assign Permissions

Select the specific permissions this role should have. Permissions are grouped by module (Tasks, Users, Agents, Payments, etc.).

4

Save and Assign

Save the role, then assign it to users. Changes take effect immediately — no logout required.

Permission Categories

Permissions are organized into modules. Each module typically provides create, read, update, and delete actions.

Module Example Permissions Description
Users users.create, users.read, users.update, users.delete Manage user accounts within the organization
Roles roles.create, roles.read, roles.update, roles.delete Create and manage roles and their permissions
Tasks tasks.create, tasks.read, tasks.update, tasks.delete Create, view, edit, and cancel delivery tasks
Agents agents.create, agents.read, agents.update, agents.delete Manage delivery agents and their profiles
Customers customers.create, customers.read, customers.update, customers.delete Manage customer records
Payments payments.read, payments.update View and manage payment records and COD collection
Settings settings.read, settings.update View and modify organization-level settings
Analytics analytics.read Access dashboards, reports, and performance metrics

Inviting Users

Organization Admins can invite new users to join their organization. Each invited user must be assigned a role at the time of invitation.

Invitation Flow

1

Send Invitation

Navigate to Users and click "Invite User". Enter the user's email address and select a role.

2

User Receives Email

The invited user receives an email notification with a link to set up their account and password.

3

Account Activation

The user clicks the link, sets their password, and gains access to the organization with the assigned role's permissions.

Principle of Least Privilege

When creating custom roles, start with the minimum set of permissions needed for the job function and add more as requirements become clear. This reduces the risk of accidental data access or modification.

User Fields Reference

Field Type Required Description
firstName String Yes User's first name
lastName String Yes User's last name
email String Yes Unique email address (used for login)
password String Yes Account password (hashed, never stored in plain text)
phone String No Phone number for contact and SMS notifications
roleId Number Yes The role assigned to this user
isActive Boolean No Whether the user can log in (defaults to true)

Next Steps

↑↓ Navigate ↵ Open Esc Close