> ## Documentation Index
> Fetch the complete documentation index at: https://ownpay.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests.

# Roles and Permissions - RBAC for Admin and Brand Access

> Define role-based access control (RBAC) roles and map granular capability flags across OwnPay's system, brand, and reporting admin modules.

OwnPay implements a Role-Based Access Control (RBAC) authorization layer. Super-administrators can define distinct roles (e.g., Owner, Customer Support, Accountant) and select precisely which actions users with that role can take. Permissions are grouped logically by modules like Gateways, Payments, People, and Developers.

## Getting here

1. Log in to the OwnPay admin dashboard as the super-administrator
2. Under the **PEOPLE** section in the left sidebar, click **Roles & Permissions**

## Page sections

### 1. Active roles list

Lists all created roles defined on the platform:

* **ROLE:** Human-readable title of the role (e.g., `Owner`)
* **SLUG:** System identifier used in database permission checks
* **DESCRIPTION:** Text describing the role's scope
* **PERMISSIONS:** Total number of permission checkboxes active for this role
* **TYPE:** Indicates whether the role is a default `System` role or a user-created brand role
* **ACTIONS:** Click **Edit** to modify name, description, or assigned capability flags

### 2. Available permissions grid

An index of all permission nodes defined in the codebase, grouped by module:

* **DEVELOPERS:** `Manage API Keys`, `View API Keys`
* **GATEWAYS:** `Manage Gateways`, `View Gateways`
* **MOBILE:** `Manage Devices`, `View Devices`, `Manage SMS`, `View SMS`
* **PAYMENTS:** `Manage Invoices`, `View Invoices`, `Manage Payment Links`, `View Payment Links`, `Manage Transactions`, `View Transactions`
* **PEOPLE:** `Manage Brands`, `View Brands`, `Manage Customers`, `View Customers`, `Manage Staff`, `View Staff`
* **SYSTEM:** `Admin Access`, `Manage Domains`, `View Domains`, `Manage Plugins`, `View Plugins`, `Manage Settings`, `View Settings`, `View Audit Log`, `Balance Verification`, `View Reports`, `System Update`

## Step-by-step: creating a new custom role

1. Navigate to the **Roles & Permissions** page
2. Click the **+ Create Role** button
3. In the form, type a **Role Name** (e.g., `Finance Auditor`) and a brief **Description**
4. In the **Edit Role** section below, select the specific permissions required (e.g., check `View Transactions`, `View Invoices`, and `View Reports`)
5. Click the **Create Role** button to save the new role category

## Permissions resolution hook

When any request is sent to the `/admin/*` panel, the system routes the request through `OwnPay\Middleware\PermissionMiddleware`. The middleware matches the route against the defined permission mapping. For example, opening the `/admin/settings` route requires the `settings.view` permission. If the user's role does not contain this permission flag, the request is aborted and a **403 Forbidden** page is displayed.

## Best practices

* Create specific, restricted roles for external users or support staff (e.g., `Support Staff` who can only view transactions)
* Write clear descriptions for custom roles so other administrators understand their purpose
* Do not modify default `System` roles like `Owner` unless absolutely necessary
* Do not give general staff roles access to `Manage API Keys` or `Manage Domains` as these contain sensitive cryptographic credentials

<Warning>
  Only super-administrators can access and edit the Roles & Permissions panel. Never assign the `staff.manage` permission to non-owners, as they could use it to elevate their own permissions or lock out other administrators.
</Warning>

## Common mistakes and troubleshooting

| Symptom                                     | Cause                                     | Fix                                                         |
| ------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- |
| Staff can't access a page after role change | New role has fewer permissions            | Edit the role and enable the required permission checkboxes |
| Role changes not taking effect              | Staff still logged in with cached session | Ask the staff member to log out and log back in             |
| Can't edit roles                            | Logged in as non-owner account            | Only super-administrators can manage roles                  |

## Related pages

* [Staff](/user-guide/people/staff) - Map staff members to roles
* [Audit Log](/user-guide/reports-finance/audit-log) - Audit actions performed by different roles


## Related topics

- [Security and Compliance - PCI, Encryption, and RBAC](/docs/advanced-topics/security-compliance.md)
- [Features and Capabilities](/docs/resources/features.md)
- [Staff Management - Add Team Members and Assign Roles](/docs/user-guide/people/staff.md)
- [Brands - Multi-Tenant Isolation for Payment Merchants](/docs/concepts/brands.md)
- [Audit Log - Track Admin Actions and Security Events](/docs/user-guide/reports-finance/audit-log.md)