# Permission System

{% hint style="info" %}
\*\*Related Documentation

This document provides a practical guide to roles and permissions. If you are interested in how permissions are evaluated internally, see [Access Control Model](/access-and-permissions/access-control/access-control-model.md).
{% endhint %}

***

## Overview

The role-based permission system gives you fine-grained control over what users can access and do in your PteroCA panel. Instead of just two roles (admin and user), you can now create custom roles with specific permissions, allowing you to build teams with different responsibilities.

### Key Benefits

* **Granular Control**: 93 individual permissions across 13 functional areas
* **Custom Roles**: Create roles that match your team structure (Moderator, Support Staff, Shop Manager, etc.)
* **Flexible Assignment**: Assign multiple roles to users
* **Better Security**: Grant only the permissions users actually need

### What Changed in v0.6

**Before v0.6:**

* Simple two-role system: ROLE\_ADMIN (full access) or ROLE\_USER (basic access)
* No ability to create custom roles
* All admins had identical permissions

**After v0.6:**

* 93 granular permissions organized into 13 categories
* Create unlimited custom roles with specific permission sets
* Separate view and edit permissions for Settings
* New `pterodactyl_root_admin` permission for Pterodactyl Panel access
* Automatic menu visibility based on permissions

***

## Understanding Roles and Permissions

### What are Permissions?

Permissions are individual access rights that control specific actions in the panel. Each permission allows a user to perform one specific action.

**Examples:**

* `access_users` - View the users list
* `edit_product` - Edit product details
* `access_settings_payment` - View payment settings

### What are Roles?

Roles are collections of permissions that you assign to users. Instead of assigning 20 individual permissions to a user, you assign them a role (like "Support Staff") that contains those 20 permissions.

**Benefits of using roles:**

* Easier to manage permissions for multiple users
* Consistency across team members with the same responsibilities
* Quickly grant or revoke access by changing role assignments

### Built-in System Roles

PteroCA includes two protected system roles that cannot be deleted or modified:

#### Admin Role

* **Permissions:** ALL 93 permissions
* **Use for:** System administrators with full access
* **Protected:** Cannot edit or delete

#### User Role

* **Permissions:** 12 basic user permissions
* **Use for:** Regular customers/users
* **Protected:** Cannot edit or delete
* **Includes:**
  * Access dashboard, shop, wallet
  * Manage own servers
  * Purchase and renew servers
  * View own payments
  * Edit account settings
  * SSO access to Pterodactyl

***

## All Permissions (93 Total)

Permissions are organized into 13 functional categories. Each permission controls access to a specific feature or action.

### 1. Dashboard (2 permissions)

| Permission              | Description                              |
| ----------------------- | ---------------------------------------- |
| `access_dashboard`      | View main dashboard                      |
| `access_admin_overview` | View admin overview page with statistics |

***

### 2. User Management (5 permissions)

| Permission     | Description         |
| -------------- | ------------------- |
| `access_users` | View users list     |
| `view_user`    | View user details   |
| `create_user`  | Create new users    |
| `edit_user`    | Edit existing users |
| `delete_user`  | Delete users        |

***

### 3. Server Management (10 permissions)

| Permission               | Description                                 |
| ------------------------ | ------------------------------------------- |
| `access_servers`         | View servers list                           |
| `view_server`            | View server details                         |
| `edit_server`            | Edit server configuration                   |
| `delete_server`          | Delete servers                              |
| `access_server_logs`     | View server activity logs                   |
| `access_server_products` | View server products list                   |
| `view_server_product`    | View server product details                 |
| `edit_server_product`    | Edit server products                        |
| `delete_server_product`  | Delete server products                      |
| `create_server`          | Create new servers manually (admin feature) |

***

### 4. Shop (12 permissions)

| Permission          | Description                        |
| ------------------- | ---------------------------------- |
| `access_shop`       | Access the shop (user feature)     |
| `access_categories` | View categories list               |
| `view_category`     | View category details              |
| `create_category`   | Create new categories              |
| `edit_category`     | Edit existing categories           |
| `delete_category`   | Delete categories                  |
| `access_products`   | View products list                 |
| `view_product`      | View product details               |
| `create_product`    | Create new products                |
| `edit_product`      | Edit existing products             |
| `delete_product`    | Delete products                    |
| `copy_product`      | Copy product to create new product |

***

### 5. Payment (3 permissions)

| Permission        | Description                    |
| ----------------- | ------------------------------ |
| `access_wallet`   | Access wallet/recharge balance |
| `access_payments` | View payments list (admin)     |
| `view_payment`    | View payment details           |

***

### 6. Voucher (8 permissions)

| Permission              | Description                |
| ----------------------- | -------------------------- |
| `access_vouchers`       | View vouchers list         |
| `view_voucher`          | View voucher details       |
| `create_voucher`        | Create new vouchers        |
| `edit_voucher`          | Edit existing vouchers     |
| `delete_voucher`        | Delete vouchers            |
| `access_voucher_usages` | View voucher usage history |
| `view_voucher_usage`    | View voucher usage details |
| `show_voucher_usages`   | Show voucher usage reports |

***

### 7. Logs (6 permissions)

| Permission           | Description             |
| -------------------- | ----------------------- |
| `access_logs`        | View system logs list   |
| `view_log`           | View system log details |
| `access_email_logs`  | View email logs list    |
| `view_email_log`     | View email log details  |
| `access_server_logs` | View server logs list   |
| `view_server_log`    | View server log details |

***

### 8. Plugins (8 permissions)

| Permission         | Description               |
| ------------------ | ------------------------- |
| `access_plugins`   | View plugins list         |
| `view_plugin`      | View plugin details       |
| `enable_plugin`    | Enable plugins            |
| `disable_plugin`   | Disable plugins           |
| `install_plugin`   | Install new plugins       |
| `uninstall_plugin` | Uninstall plugins         |
| `upload_plugin`    | Upload plugin packages    |
| `configure_plugin` | Configure plugin settings |

***

### 9. Roles & Permissions (7 permissions)

| Permission           | Description             |
| -------------------- | ----------------------- |
| `access_roles`       | View roles list         |
| `view_role`          | View role details       |
| `create_role`        | Create new roles        |
| `edit_role`          | Edit existing roles     |
| `delete_role`        | Delete roles            |
| `access_permissions` | View permissions list   |
| `view_permission`    | View permission details |

***

### 10. Settings (14 permissions)

Settings permissions are split into **access** (view) and **edit** permissions for each settings category. This allows you to create read-only admin roles or specialized roles with editing rights only for specific settings.

| Permission                    | Description                                             |
| ----------------------------- | ------------------------------------------------------- |
| `access_settings_general`     | **View** general settings (site URL, title, language)   |
| `edit_settings_general`       | **Edit** general settings                               |
| `access_settings_pterodactyl` | **View** Pterodactyl integration settings               |
| `edit_settings_pterodactyl`   | **Edit** Pterodactyl integration settings               |
| `access_settings_security`    | **View** security settings (verification, CAPTCHA, TOS) |
| `edit_settings_security`      | **Edit** security settings                              |
| `access_settings_payment`     | **View** payment gateway settings                       |
| `edit_settings_payment`       | **Edit** payment gateway settings                       |
| `access_settings_email`       | **View** email/SMTP settings                            |
| `edit_settings_email`         | **Edit** email/SMTP settings                            |
| `access_settings_theme`       | **View** theme/appearance settings                      |
| `edit_settings_theme`         | **Edit** theme/appearance settings                      |
| `access_settings_plugin`      | **View** plugin settings                                |
| `edit_settings_plugin`        | **Edit** plugin settings                                |

**Use cases:**

* **Read-only support role**: Grant `access_settings_*` permissions to view all settings without editing rights
* **Payment manager**: Grant only `edit_settings_payment` to manage payment configuration
* **Security officer**: Grant only `edit_settings_security` to manage security configuration

***

### 11. Themes (8 permissions)

| Permission          | Description                 |
| ------------------- | --------------------------- |
| `access_themes`     | View themes list            |
| `view_theme`        | View theme details          |
| `set_default_theme` | Set default theme for panel |
| `configure_theme`   | Configure theme settings    |
| `upload_theme`      | Upload theme packages       |
| `copy_theme`        | Copy existing themes        |
| `export_theme`      | Export themes as packages   |
| `delete_theme`      | Delete themes               |

***

### 12. User Features (9 permissions)

These permissions control user-facing features (non-admin functionality).

| Permission               | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `access_my_account`      | Access account settings page                   |
| `access_my_servers`      | View own servers list                          |
| `access_user_payments`   | View own payments list                         |
| `view_user_payment`      | View own payment details                       |
| `edit_user_account`      | Edit account settings (name, avatar, password) |
| `continue_payment`       | Continue incomplete payment sessions           |
| `purchase_server`        | Purchase new servers from shop                 |
| `renew_server`           | Renew existing server subscriptions            |
| `access_pterodactyl_sso` | SSO redirect to Pterodactyl Panel              |

***

### 13. Pterodactyl Integration (1 permission)

| Permission               | Description                                  |
| ------------------------ | -------------------------------------------- |
| `pterodactyl_root_admin` | Grant root admin access in Pterodactyl Panel |

This special permission controls whether users are granted root administrator status when accessing the Pterodactyl Panel. This is separate from PteroCA admin permissions, allowing you to have PteroCA admins who are NOT Pterodactyl root admins.

**Important:** Only grant this to fully trusted administrators.

***

## Managing Roles

### Creating a Custom Role

To create a new role with specific permissions:

1. **Navigate to Roles Management:**
   * Open the Admin Panel
   * Go to **Roles & Permissions** → **Roles**
2. **Click "Add role"**
3. **Fill in role details:**
   * **Name**: Internal identifier (lowercase, e.g., `moderator`, `support_staff`)
   * **Display Name**: User-friendly name (e.g., "Moderator", "Support Staff")
   * **Description**: Optional explanation of the role's purpose
4. **Select Permissions:**
   * Permissions are grouped by category for easy navigation
   * Check the permissions you want to grant to this role
   * You can select any combination of permissions
5. **Click "Save"**

The new role is now available for assignment to users.

### Editing a Role

You can edit custom roles (non-system roles) to change their display name, description, or assigned permissions:

1. Go to **Roles & Permissions** → **Roles**
2. Click on the role you want to edit
3. Click **Edit role**
4. Make your changes
5. Click **Save**

{% hint style="warning" %}
**System Role Protection**

The built-in **admin** and **user** roles cannot be edited or deleted. They are protected system roles.
{% endhint %}

### Deleting a Role

You can delete custom roles that are not assigned to any users:

1. Go to **Roles & Permissions** → **Roles**
2. Click on the role you want to delete
3. Click **Delete role**
4. Confirm deletion

{% hint style="danger" %}
**Cannot Delete Roles with Users**

You cannot delete a role that is currently assigned to users. You must first remove the role from all users or assign them different roles.
{% endhint %}

***

## Assigning Roles to Users

### Via User Management

1. **Navigate to Users:**
   * Go to **Admin Panel** → **Users**
2. **Edit a User:**
   * Click on the user you want to modify
   * Click **Edit user**
3. **Assign Roles:**
   * Find the **Roles** field
   * Select one or more roles from the dropdown
   * Users can have multiple roles (they will receive the union of all permissions)
4. **Save Changes:**
   * Click **Save user**

### Via CLI Command

You can also assign roles when creating users via the command line:

```bash
# Create a user with the admin role
php bin/console pteroca:user:create admin@example.com securePassword ROLE_ADMIN

# Create a user with the default user role
php bin/console pteroca:user:create user@example.com password123

# Create a user with a custom role (v0.6+)
php bin/console pteroca:user:create moderator@example.com password123 Moderator
```

See the [User Management Commands](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/for-developers/cli-reference/user-management/README.md#create-new-user) documentation for more details.

***

## Example Role Scenarios

Here are some common role configurations you might want to create:

### Support Staff Role

**Purpose:** View system data and user information without editing capabilities

**Permissions to grant:**

* `access_admin_overview` - View dashboard statistics
* `access_users`, `view_user` - View user details (no editing)
* `access_servers`, `view_server` - View server information
* `access_logs`, `view_log` - View system logs
* All `access_settings_*` permissions (read-only access to settings)

**What they CAN'T do:**

* Edit users, servers, or settings
* Create or delete anything
* Modify system configuration

***

### Shop Manager Role

**Purpose:** Manage products and categories without access to other admin functions

**Permissions to grant:**

* `access_admin_overview` - View dashboard
* `access_categories`, `view_category`, `create_category`, `edit_category`, `delete_category` - Full category management
* `access_products`, `view_product`, `create_product`, `edit_product`, `delete_product`, `copy_product` - Full product management

**What they CAN'T do:**

* Manage users or servers
* Change system settings
* View logs or payments

***

### Theme Manager Role

**Purpose:** Manage themes and appearance without access to other admin functions

**Permissions to grant:**

* `access_admin_overview` - View dashboard
* `access_themes`, `view_theme`, `set_default_theme`, `configure_theme` - Full theme management
* `upload_theme`, `copy_theme`, `export_theme`, `delete_theme` - Theme operations
* `access_settings_theme`, `edit_settings_theme` - Theme settings access

**What they CAN'T do:**

* Manage users, servers, or products
* Change non-theme settings
* View logs or payments

***

### Moderator Role

**Purpose:** Moderate content and manage basic user issues

**Permissions to grant:**

* `access_admin_overview` - View dashboard
* `access_users`, `view_user`, `edit_user` - Manage users (no deletion)
* `access_servers`, `view_server`, `edit_server` - Manage servers
* `access_logs`, `view_log`, `access_server_logs`, `view_server_log` - View logs

**What they CAN'T do:**

* Delete users or servers
* Change system settings
* Manage products or payments

***

### Billing Manager Role

**Purpose:** Handle payments and financial settings

**Permissions to grant:**

* `access_admin_overview` - View dashboard
* `access_payments`, `view_payment` - View all payments
* `access_vouchers`, `view_voucher`, `create_voucher`, `edit_voucher`, `delete_voucher` - Full voucher management
* `access_settings_payment`, `edit_settings_payment` - Edit payment settings
* `access_users`, `view_user`, `edit_user` - Manage user balances

**What they CAN'T do:**

* Manage servers or products
* Change non-payment settings
* Access system logs

***

### Security Officer Role

**Purpose:** Manage security settings and monitor logs

**Permissions to grant:**

* `access_admin_overview` - View dashboard
* `access_settings_security`, `edit_settings_security` - Edit security settings
* `access_logs`, `view_log` - View system logs
* `access_email_logs`, `view_email_log` - View email logs
* `access_server_logs`, `view_server_log` - View server logs
* `access_users`, `view_user` - View users

**What they CAN'T do:**

* Manage products, servers, or payments
* Change non-security settings
* Edit users

## Security Considerations

### System Role Protection

The built-in **admin** and **user** roles are protected:

* ❌ Cannot be deleted
* ❌ Cannot edit role name or system flag
* ❌ Cannot modify permissions
* ✅ Can view role details

This prevents accidental lockout and ensures system stability.

### Permission Validation

When creating or editing roles:

* Permission codes must be unique across the system
* Plugin permissions follow naming conventions
* Invalid permissions are rejected

### Audit Logging

All permission-related actions are logged:

* Role creation, editing, deletion
* Permission assignments
* User role changes
* Plugin permission synchronization

### Best Practices

1. **Follow the Principle of Least Privilege**
   * Grant only the permissions users actually need
   * Don't give full admin access when a custom role would suffice
2. **Regularly Review Role Assignments**
   * Check which users have which roles
   * Remove unnecessary permissions
   * Update roles as team responsibilities change
3. **Use Descriptive Role Names**
   * Make it clear what each role is for
   * Add descriptions to explain the role's purpose
4. **Test Custom Roles**
   * Create a test user with the new role
   * Verify they can access exactly what they should
   * Check that restricted areas are properly blocked
5. **Protect Sensitive Permissions**
   * Only grant `pterodactyl_root_admin` to fully trusted administrators
   * Be cautious with `edit_settings_*` permissions
   * Limit `delete_*` permissions to appropriate roles

***

## Frequently Asked Questions

### Can a user have multiple roles?

**Yes!** Users can be assigned multiple roles. They will receive the union of all permissions from all assigned roles.

Example: A user assigned both "Support Staff" and "Shop Manager" roles will have permissions from both roles.

***

### What happens if I delete a role that users are assigned to?

You **cannot** delete a role that is currently assigned to users. The system will prevent the deletion and show an error message.

**Solution:** First remove the role from all users (or assign them different roles), then delete the role.

***

### Can I edit the permissions of the admin role?

**No.** The admin and user roles are system-protected roles. You cannot modify their permissions or delete them.

**Solution:** If you need a role with slightly different permissions than admin, create a new custom role with your desired permissions.

***

### How do I give someone access to only view logs?

Create a custom role with only log viewing permissions:

1. Create role: "Log Viewer"
2. Assign permissions:
   * `access_admin_overview`
   * `access_logs`, `view_log`
   * `access_email_logs`, `view_email_log`
   * `access_server_logs`, `view_server_log`
3. Assign the role to the user

***

### What's the difference between access and edit permissions for Settings?

* **`access_settings_*`**: Allows viewing the settings page (read-only)
* **`edit_settings_*`**: Allows editing and saving changes to settings

This separation lets you create read-only admin roles who can see all settings but cannot change them.

***

### Can plugins add their own permissions?

**Yes!** Plugins can register custom permissions that will appear in the permission list and can be assigned to roles.

Plugin permissions follow the naming convention: `PLUGIN_{PLUGIN_NAME}_{PERMISSION}`

***

### Will my custom roles be lost if I update PteroCA?

**No.** Custom roles are stored in the database and will be preserved across updates. Only the system roles (admin, user) are managed by migrations.

***

### How do I create a role that can only manage specific settings?

Create a custom role and grant only the specific `edit_settings_*` permissions you want:

**Example: Payment Configuration Manager**

* `access_admin_overview`
* `access_settings_payment`
* `edit_settings_payment`

This user can view and edit payment settings, but cannot access other settings categories.

***

## Related Documentation

* [Access Control Model](/access-and-permissions/access-control/access-control-model.md) - Technical implementation details
* [Access Control Overview](/access-and-permissions/access-control.md) - Introduction to the v0.6 permission system
* [CLI Reference](/for-developers/cli-reference/user-management.md) - Create users with specific roles via command line
* [Core Configuration](/core-configuration/core-configuration.md) - Settings configuration (requires appropriate permissions)

***

{% hint style="success" %}
**Need Help?**

If you have questions about the role and permission system:

* Open an issue on [GitHub](https://github.com/PteroCA-Org/panel/issues)
* Join our [Discord community](https://discord.com/invite/Gz5phhuZym)
* Check the [FAQ](/help-and-maintenance/faq.md)
  {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pteroca.com/access-and-permissions/access-control/roles-and-permissions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.