How to Create a New System Role and Map Permissions

Intro

BallersBook uses a role-based access control (RBAC) system to manage what each user can see and do. As a super-admin, you can create new system roles and assign specific permissions to them. This lets you tailor access for different staff types, parents, or reviewers without giving everyone the same level of control. In this guide, you will learn how to define a new role, select its permissions from the access matrix, and save it so it becomes available for assignment to club members.

Prerequisites

• A super-admin account (the super-admin role).
• Access to the Global Preferences section (usually under Admin in the main navigation).
• An understanding of the permissions listed in the RBAC matrix (see manage_drills, manage_sessions, etc.).
• A clear idea of what the new role should be able to do (e.g., “Assistant Coach” with limited drill management).

Step-by-step

1. Log in with your super-admin credentials. Navigate to the Admin menu and select Global Preferences.

2. In the Global Preferences screen, locate the Roles & Permissions section. Click Roles.

📸 A screenshot of the Global Preferences menu with “Roles & Permissions” highlighted.

3. Click New Role. A form or modal opens.

4. Enter the Role Name (e.g., Assistant Coach) and an optional Description (e.g., “Can create and edit drills, but not delete them or manage sessions”).

5. Under Permissions, you will see the RBAC matrix with a list of all available permissions (like manage_drills, manage_sessions, manage_finance). Check the boxes for each permission you want the new role to have.

The matrix is grouped by feature area (Drills, Sessions, Finance, Communications, etc.). The exact permission names match those defined in the system’s access control list. For reference, see the PAGE_ACCESS.md documentation which lists permissions such as manage_drills, manage_sessions, manage_invites, and view_finance.

6. When you have selected the desired permissions, click Save Role. The new role will appear in the role list.

7. (Optional) To test the role, assign it to a user via their profile. Go to Club Management → Users → select a user → Edit Roles, add the new role, and save. Ask the user to log out and back in, then verify they see only the features you enabled.

Tips & Pitfalls

• Permissions are cumulative. A user with multiple roles gets the union of all permissions from each role (unless a role has specific overrides). Plan roles to be as granular as possible.
• Once a role is saved, you cannot delete it if any user is currently assigned that role. You must first reassign those users to another role.
• The RBAC matrix does not include the super-admin role; that role bypasses all permissions and cannot be edited or removed.
• If a permission is missing from the matrix that you believe should exist, contact support. The matrix is maintained by the system and updated with each release.
• Always test a new role with a dummy user before rolling it out to many staff members.

Summary

Creating a new system role and mapping permissions is a straightforward process in Global Preferences. You define the role, check the appropriate permissions from the RBAC matrix, and save. The role then becomes available for assignment to any user in your club. After creating a role, assign it to one user and verify access to confirm the permissions work as intended. Next, you might want to document the roles you have created and share them with your club’s administrators for consistent use.