Roles & Permissions

QuickBox Pro uses Role-Based Access Control (RBAC) to manage what administrative actions users can perform. Roles are collections of permissions — assign a role to a user, and they gain all the permissions that role includes. The Roles & Permissions page lets you view, create, and manage roles with a full permission matrix editor.

Admin only

Roles & Permissions requires admin privileges. admin.roles.read is needed to view roles, and admin.roles.manage is needed to create, edit, or delete roles. Navigate to User Management > User Roles from the sidebar.

Key features

🛡️ Granular Permissions

35 permissions across 10 domains — control exactly what each role can do

👥 Default Roles

Four built-in system roles provide a solid starting point for most server configurations

✏️ Custom Roles

Create custom roles with any combination of permissions for specialized access levels

🔢 Priority Ordering

Roles have priority levels to resolve conflicts when multiple access rules apply

🔒 System Protection

System roles cannot be modified or deleted — they always maintain their defined permissions

👤 Single-Role Assignment

Each user has exactly one role, making permission resolution straightforward

Understanding roles

A role defines which administrative capabilities a user has in the dashboard. Roles control actions like managing other users, changing settings, installing software, and accessing system tools. They are separate from groups, which control application access.

Key concepts:

Each user is assigned exactly one role at a time
Roles contain a set of permissions drawn from the permission matrix
Higher-priority roles take precedence when evaluating access
System roles are immutable — they cannot be edited or deleted

Default roles

QuickBox Pro ships with four system roles and one optional custom role:

Role	Priority	Type	Permissions
Super Admin	100	System	All 35 admin permissions including impersonation
Administrator	90	System	All admin permissions except user impersonation
Staff	50	Custom	Empty by default — customize to create a middle-tier access level
User	10	System	No admin permissions — application access is controlled by groups
Banned	0	System	No permissions — account is locked

Super Admin vs Administrator

The Super Admin role includes the admin.users.impersonate permission, which allows logging in as another user. The Administrator role has all other permissions but cannot impersonate users. The Super Admin account — the account created during installation — cannot be deleted.

Permission domains

Permissions are organized into 10 domains. Each domain covers a functional area of the dashboard:

Domain	Permissions	What it controls
Users	`admin.users.read` `admin.users.create` `admin.users.update` `admin.users.delete` `admin.users.impersonate`	Viewing, creating, modifying, deleting, and impersonating user accounts
Roles	`admin.roles.read` `admin.roles.manage`	Viewing roles and creating, editing, or deleting roles
Groups	`admin.groups.read` `admin.groups.manage`	Viewing groups and managing group membership and app access
Settings	`admin.settings.read` `admin.settings.update`	Viewing and modifying all server settings pages
Sessions	`admin.sessions.read` `admin.sessions.revoke`	Viewing all user sessions and force-revoking sessions
System	`admin.system.dashboard` `admin.system.logs` `admin.system.console` `admin.system.database` `admin.system.ssl` `admin.system.vpn` `admin.system.update` `admin.system.api` `admin.system.support`	Access to System Dashboard, logs, Web Console, database management, SSL, VPN, updates, API settings, and support access
Links	`admin.links.read` `admin.links.manage`	Viewing and managing external link entries in the dashboard
Software	`admin.software.install` `admin.software.remove` `admin.software.configure`	Installing, removing, and configuring software packages
App Config	`admin.apps.config.read` `admin.apps.config.edit` `admin.apps.backup.create` `admin.apps.backup.restore` `admin.apps.backup.delete` `admin.apps.database.browse`	Viewing and editing app config files, creating and managing backups, browsing app databases
Streaming	`admin.streaming.read` `admin.streaming.manage`	Viewing the Streaming Dashboard and managing streaming settings

Creating custom roles

To create a custom role:

Click the Create Role button
Enter a role name and set a priority level
Use the permission matrix editor to select which permissions to include
Save the role

The permission matrix groups permissions by domain, so you can quickly grant or revoke entire categories of access. For example, you might create a “Support Staff” role with user read, session read, and system logs permissions — but no ability to install software or change settings.

Assigning roles to users

Roles are assigned to users from the User Admin page. Each user can hold exactly one role at a time. When you change a user’s role, their permissions update immediately.

You can also assign roles during user creation by selecting a role in the new user dialog.

Revoke sessions after role changes

When you change a user’s role, consider revoking their active sessions from User Admin so the new permissions take effect immediately across all their active logins.

CLI equivalent

Dashboard Action	CLI Command
Promote user to admin	`qb user promote -u <username>`
Demote user from admin	`qb user demote -u <username>`

Dashboard advantage

The CLI supports basic promote/demote (admin vs standard user). The full RBAC system — custom roles, granular permissions, and the permission matrix editor — is available only through the dashboard.

Best practices

Do

Follow the principle of least privilege — give each role only the permissions it needs, nothing more
Use the Staff role (or create a custom role) for users who need more than basic access but should not have full admin privileges
Document what each custom role is intended for so future admins understand the access model
Review role assignments periodically to ensure users have appropriate access levels
Revoke sessions after changing a user's role to ensure the new permissions take effect immediately

Don't

Don't give the Super Admin role to multiple users unless necessary — the impersonation permission is powerful and should be restricted
Don't modify system roles — create custom roles instead if the defaults don't meet your needs
Don't assign the Administrator role to users who only need access to specific features — create a custom role with targeted permissions
Don't forget that roles control admin capabilities while groups control app access — you need both to fully configure a user's access

FAQ

Roles control administrative capabilities — what actions a user can perform in the dashboard (managing users, changing settings, installing software). Groups control application access — which installed applications a user can see and use. A user needs both a role and a group membership to have complete access.

No. Each user has exactly one role at a time. This is by design — single-role assignment makes permission resolution straightforward and avoids conflicts. If you need a role with a specific combination of permissions, create a custom role.

You should reassign affected users to another role before deleting a custom role. System roles (Super Admin, Administrator, User, Banned) cannot be deleted.

Yes. The role list shows a summary of each role, and you can view the full permission details by clicking on any role. The permission matrix editor shows all permissions grouped by domain.

Priority is a numeric value that orders roles from most privileged (highest number) to least privileged. It determines the hierarchy when evaluating access. Super Admin has priority 100, Administrator has 90, and User has 10. Custom roles can be set to any priority level.

User Admin

Assign roles to users and manage accounts

Groups

Control application access through group membership

Security Settings

Network enforcement and IP management

General Settings

Server-wide configuration and feature flags

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support

Feature Previews

Community Configs

Active Discussions

Join Discord Server