Roles & permissions

Overview#

Access to the CentraPoint dashboard is controlled by permissions of the form resource:action, for example invoices:write or reports:build. Every user has:

• a built-in role (Admin, Staff or Viewer), each with a fixed default set of permissions; and optionally
• a custom role defined by your organisation under Settings → Roles. A custom role's permission list replaces the built-in role's defaults; it is not added to them.

Roles control dashboard users only. API requests are authorised by API key, not by role; see Authentication.

Built-in roles#

By default only Admins can see and manage users, roles, API keys, webhooks, the audit log, accounting connections, payment providers and email settings. Staff additionally get the email log and accounting CSV exports. Issuing refunds, subscription settings, debit order settings and mandate approval are Admin-only by default. The catalogue shows exactly which built-in roles hold each permission.

Built-in roles cannot be changed. Open one under Settings → Roles to see its permissions, and use Duplicate as custom role to start a custom role from it.

Custom roles#

Settings → Roles lists the built-in roles and your custom roles, with how many permissions each has and how many users use it. You need roles:read to see this page and roles:write to create, edit or delete custom roles (both Admin-only by default).

Creating and editing a custom role#

Click New role, or Duplicate on an existing role, and fill in:

• Name: 2 to 100 characters, unique within your organisation. Admin, Staff and Viewer (in any capitalisation) are reserved.
• Description (optional, up to 500 characters).
• Permissions: a grid of resources and actions (View, Manage, Approve, Settings, Build, Manage all, Export), grouped as in the catalogue below. Select at least one. Ticking any action also ticks View for that resource, and unticking View clears the other actions on it. Select all, All view and Clear speed this up.

Changes to a custom role apply to everyone assigned to it from their next page load or action; they do not need to sign in again. Creating, updating and deleting roles are recorded in the audit log (role.create, role.update with the permissions added and removed, and role.delete).

Deleting a custom role#

Open the role and delete it. A role can only be deleted when no users are assigned to it; move its users to another role first. Deleting cannot be undone.

Giving a user a role#

Roles are assigned under Settings → Users (needs users:write, Admin-only by default):

• Add user: choose the built-in Role (Staff is preselected) and, if your organisation has custom roles, an optional Custom role. Leave the password blank to email the user an invitation to set their own.
• Existing users: change the built-in role or custom role in the user's row and click Save. Choose No custom role to go back to the built-in role's defaults.

These rules stop anyone from widening their own access:

• You cannot give a user (new or existing) any permission you do not have yourself.
• You cannot manage a user who currently has permissions you do not have.
• You cannot change your own role or custom role, or deactivate yourself.

Adding or reactivating users counts towards your plan's user limit. Your current role (the custom role's name if you have one) is shown in the user menu at the top of the dashboard.

How permissions are applied#

• Your effective permissions are read from the database on every request, so role changes take effect straight away. Deactivated users have no permissions.
• The dashboard menu only shows areas you have the view permission for (and, for plan features, that your plan includes). Actions are checked against the matching permission on the server.
• Permissions never override your plan. For example, reports:build does nothing on a plan without the Report builder, and write permissions are refused while your organisation's account is read-only.
• Your built-in role is still recorded when you have a custom role, but access is decided by permissions only. For example, a saved report can be edited by its owner or by anyone with reports:manage (see Reports).
• Platform administrators always have every permission.

Permission catalogue#

Every permission, as defined by the platform (62 in total). The label is what the permission grid shows; the last column lists the built-in roles that have the permission by default.