Access Control

PteroCA uses a comprehensive role-based permission system with 84 granular permissions, replacing the simple ROLE_ADMIN/ROLE_USER system. You can now create custom roles with specific permissions tailored to your team's needs.

---

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: 84 individual permissions across 12 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:

• 84 granular permissions organized into 12 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 84 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 (84 Total)

Permissions are organized into 12 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 (9 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

---

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. 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

---

12. 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

System Role Protection

The built-in admin and user roles cannot be edited or deleted. They are protected system roles.

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

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.

---

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:

# Create a user with the admin role
php bin/console pteroca:user:create [email protected] securePassword ROLE_ADMIN

# Create a user with the default user role
php bin/console pteroca:user:create [email protected] password123

# Create a user with a custom role (v0.6+)
php bin/console pteroca:user:create [email protected] password123 Moderator

See the User Management Commands 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

---

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

---

How Permissions Work

Permission Checking

When a user tries to access a feature, PteroCA checks if they have the required permission:

1. User requests access to a feature (e.g., clicks "Users" menu item)

2. System retrieves user's roles from the database

3. System collects all permissions from all assigned roles

4. System checks if any permission matches what's required

5. Access granted or denied based on the check

Menu Visibility

The admin menu automatically adapts to show only items the user can access:

• Menu items are hidden if the user lacks the required permission

• Submenus use OR-logic: A submenu is visible if the user has ANY child permission

  • Example: "Shop" submenu appears if user has access_categories OR access_products

• Empty submenus are hidden completely

This provides a clean interface showing only relevant options.

Multi-layer Security

Permissions are enforced at multiple levels:

1. Menu Level: Items hidden if user lacks permission

2. Controller Level: Access denied even if user knows the URL

3. Service Level: Business logic validates permissions

4. Database Level: Foreign key constraints prevent unauthorized data changes

You Cannot Bypass Permissions

Even if you know the direct URL to a page, you cannot access it without the required permission. The system checks permissions at every level, not just in the menu.

---

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

• CLI Reference - Create users with specific roles via command line

• Customization - Settings configuration (requires appropriate permissions)

---

Need Help?

If you have questions about the role and permission system:

• Open an issue on GitHub

• Join our Discord community

• Check the FAQ