Roles & Permissions

QuickBox Pro uses Role-Based Access Control (RBAC) to manage what administrative actions users can perform. Roles grant administrative capabilities — managing users, changing settings, installing software, accessing system tools. Assign one or more roles to a user, and their permissions are the combined set. The User Roles page lets you view, create, and manage roles with a permission matrix editor.

Who can manage roles

Managing roles is gated by permission, not by which account you use: admin.roles.read is required to view roles, and admin.roles.manage is required to create, edit, or delete them. Administrator-level accounts always have access. Navigate to User Management > User Roles from the sidebar.

Roles grant admin capabilities — not media or app access

Roles only carry administrative (admin.*) permissions. They cannot grant access to applications or to the Asset Management Center. App access comes from groups, and media features (media.*) come from groups or per-user overrides. See Granting media and app access below.

Key features

Granular Permissions

35 administrative 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

Role Assignment

Assign one or more roles to a user — their permissions are the combined set

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 and media features.

Key concepts:

A user can be assigned one or more roles — their permissions are the union of every role they hold
Roles contain a set of admin.* permissions drawn from the permission matrix
Higher-priority roles surface first in listings and ordering
System roles are immutable — they cannot be edited or deleted
Administrator-level accounts (Super Admin / Administrator) pass every permission check regardless of the exact permission list on their role

Default roles

QuickBox Pro seeds four built-in system roles:

Role	Priority	Type	Permissions
Super Admin	100	System	Every administrative permission, including impersonation
Administrator	90	System	Every administrative permission except user impersonation
User	10	System	No admin permissions — application and media access come from groups
Banned	0	System	No permissions — account is restricted

There is no built-in “Staff” role

QuickBox Pro does not seed a Staff role. If you want a middle tier between User and Administrator — for example a support helper who can read users and view logs but not change settings — create a custom role for it. “Staff” is a tier you build, not a preset.

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 every other permission but cannot impersonate users. The Super Admin account created during installation cannot be deleted.

Admins always have everything — automatically

An Administrator-level account passes every permission check as a built-in fallback, regardless of the exact permissions listed on its role. You never need to “add” permissions to an admin’s role to unlock a feature — admin status alone grants full access. Likewise, there is no raw access-level number to edit in the dashboard; you make someone an admin by assigning them the Super Admin or Administrator role (see Making a user an administrator).

Permission domains

The permission registry contains 35 administrative permissions 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
Branding	`admin.branding.update`	Modifying instance branding — logos, favicon, default avatar and banner
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
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 app backups, browsing app databases
Streaming	`admin.streaming.read` `admin.streaming.manage`	Viewing the Streaming Dashboard and managing streaming settings

Some permissions have no individual checkbox in the matrix

The permission matrix editor exposes individual checkboxes for nine categories (User Management, Group Management, Role Management, Software Management, System Administration, Settings, Session Management, External Links, and Streaming). The Branding and App Config permissions — admin.branding.update, admin.apps.config.*, admin.apps.backup.*, and admin.apps.database.browse — are not individually selectable in the matrix today. They are granted only by the editor’s Select all action, which grants every permission. This means you cannot currently build a custom role that grants only branding (or only app-backup) access — that permission arrives only as part of a full-access role. Administrator-level accounts already have these capabilities through the admin fallback.

Creating custom roles

To create a custom role:

Click the Create Role button
Enter a role name and set a priority level (1–100; higher means more authority)
Use the permission matrix editor to select which permissions to include — or use Select all to grant every permission
Save the role

The permission matrix groups permissions by category, so you can quickly grant or revoke whole areas of access. For example, you might create a support-helper role with user read, session read, and system logs permissions — but no ability to install software or change settings.

Set permissions through the matrix, not by hand

Always pick permissions using the matrix editor. It only emits valid permission keys, so you never end up with a typo that silently grants nothing. A custom role can only carry admin.* permissions; it can never grant application access or media features.

Assigning roles to users

Roles are assigned from the User Roles page (open a role and manage its assigned users) and reflected on each user’s expanded row in User Admin, where their roles appear as badges. A user can hold one or more roles, and their effective permissions are the combined set. When you change a user’s roles, their permissions update immediately.

Revoke sessions after role changes

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

Making a user an administrator

There is no access-level number to set in the dashboard. To make someone an administrator, assign them the Administrator role (or Super Admin if they also need impersonation). An admin-level account automatically passes every permission check, so you do not configure individual permissions for an admin — the role alone grants full access.

To remove admin access, unassign the Administrator / Super Admin role and assign the appropriate lower-tier role instead.

Action	CLI equivalent
Make a user an admin	`qb user promote -u <username>`
Remove a user's admin access	`qb user demote -u <username>`

The CLI promote / demote commands and the dashboard role assignment reach the same outcome — the user becomes (or stops being) an administrator. The dashboard adds the full RBAC system on top: custom roles, the granular permission matrix, and middle-tier roles between standard user and full admin.

Granting media and app access

A common question: how do I let a user open the Asset Management Center, create share links, or access specific applications? Roles cannot do this. Those grants live on two other surfaces:

You want a user to…	Grant it from
Access specific applications	Groups — a group's app categories
Use the Asset Management Center (`media.library.use`)	Groups (group grant) or User Admin (per-user override)
Create share links (`media.share.create`) or email them (`media.share.email`)	Groups or per-user override in User Admin

Media permissions resolve in a strict order: an administrator always has every media permission; otherwise an explicit per-user override (Allow or Deny, set in User Admin) is final — a Deny beats a group grant; otherwise any group that grants the permission grants it; otherwise it is denied by default. A brand-new non-admin user in the default group has no media permissions until you grant them. For the full media model, see the Asset Management Center page.

Best practices

Do

Follow the principle of least privilege — give each role only the permissions it needs, nothing more
Create a custom role for users who need more than basic access but should not have full admin privileges (there is no built-in Staff role)
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 roles so 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 try to grant app or media access through a role — roles only carry admin capabilities; use groups (app + media) and per-user overrides (media)

FAQ

Roles control administrative capabilities — what actions a user can perform in the dashboard (managing users, changing settings, installing software). Groups control application access and media features — which installed applications a user can see and use, and whether they can use the Asset Management Center. A role can never grant app or media access, and a group can never grant admin permissions. Most users need both a role (often just the standard User role) and a group membership.

Yes. A user can hold one or more roles, and their effective permissions are the combined set of every role they hold. Most setups assign a single role per user for simplicity, but multiple roles are supported.

Not through a role — roles only grant admin capabilities. Grant media.library.use (and optionally media.share.create / media.share.email) either on a group the user belongs to, or as a per-user override in User Admin. A per-user Allow or Deny is final; otherwise any group that grants the permission grants it. By default a non-admin user has no media access.

Assign them the Administrator role (or Super Admin if they also need impersonation). There is no access-level number to set — admin status comes from the role, and an admin automatically passes every permission check. The CLI equivalent is qb user promote.

Not today. The admin.branding.update permission has no individual checkbox in the permission matrix — it is granted only by the editor's Select all, which grants everything. So a branding-only custom role is not currently possible. Administrator-level accounts already have branding access through the admin fallback.

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

Manage accounts, media overrides, and per-user quotas

Groups

Control application access and media features through group membership

Asset Management Center

The media features that groups and per-user overrides govern

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