Roles

Part of the IP4CMS portal. ← All module guides

What it's for — A role is a named bundle of permissions that you assign to users. Roles are the heart of access control in IP4CMS: a user can do exactly what their assigned roles allow, and nothing more. Instead of granting permissions to people one at a time, you build a few well-designed roles (for example "Finance Officer", "Front Desk", "Read-only Auditor") and assign them.

Each permission is a small, specific capability written in the format module:action:resource — for example members:read:all (read all members), families:create:all (create families), or events:manage:attendance (manage event attendance). A role holds a list of these.

There is one special permission, admin:full:access, the "Administrator Full Access" wildcard. A role with this permission can do everything, in every module, regardless of what else is or isn't ticked. Treat it as the master key.

Where to find it — In the portal sidebar, open Roles. You can also reach it from Settings → Roles. Roles is an always-on baseline module (roles) — it is part of every tenant and cannot be switched off, because access control has to exist before anything else can be governed.

Before you start — You need permission to manage roles. The screen and its buttons are gated by:

• roles:read:all — to view the list and open a role
• roles:create:all — to see Add Role and create one
• roles:update:all — to see Edit Role
• roles:delete:all — to see Delete

If you hold admin:full:access, all of these are granted automatically. Also note that the permissions you can tick when building a role are filtered by your tenant's licence — only permissions for modules your tenant is licensed for appear.

Key tasks

Create a role

1. Open Roles and click Add Role.
2. Fill in Basic Information, then choose Applicable Contexts and Permissions (covered below).
3. Click Create Role. The button stays disabled until the form is valid.

Fields:

• Role Name (required) — 2 to 50 characters. Must be unique within your tenant; saving a duplicate name is rejected.
• Description (optional) — up to 200 characters. Use it to explain who the role is for.
• Applicable Contexts (required) — at least one. See below.
• Permissions — at least one must be selected.

Select permissions

Permissions are grouped into collapsible module sections (for example Members, Locations, Events), each showing how many of its permissions you've selected (e.g. "4 / 12 selected"). Some modules have sub-modules nested underneath (for example Members: Ranks, Members: Requests), shown indented inside their parent.

• Tick individual permissions, or use Select All / Clear All on a module header to toggle the whole section at once.
• Use the chevron button to collapse or expand a section.
• A running Selected Permissions summary at the bottom lists everything currently chosen.

At the top sits the highlighted Administrator Full Access box. Ticking it selects admin:full:access and clears and disables every other permission — a full-access role carries only that one wildcard. Untick it to go back to picking individual permissions. Only use it for trusted super-admins.

Note: if you somehow include a permission that no longer exists (for example an old one from before a module change), it is silently filtered out when the role is saved rather than blocking the save.

Context (tenant / customer / member)

Applicable Contexts decide which kinds of users a role can be assigned to. A user can only receive roles that match their own context, so this keeps internal-staff roles separate from portal-user roles. The available contexts are:

• Internal Users (tenant) — staff and internal system users. This is the default for a new role.
• Customer (customer) — users linked to customer accounts.
• Supplier (supplier) — users linked to supplier accounts.
• Member (member) — portal users for members and their families (the member-facing app).

The list of contexts you see depends on which related modules your tenant runs. Tick every context a role should be available in; you must select at least one. A role meant for back-office staff would use Internal Users; a role for the member app would use Member.

Assign roles to users

You don't assign roles from the Roles screen itself — you do it from the Users module (and the equivalent admin screens for partners, customers, suppliers, and members). When you create or edit a user there, you pick one or more roles, and the user's effective permissions become the combined list from all their roles. A user can hold several roles at once; their permissions add up.

To see how many users currently hold a role, open the role: the detail page shows a users assigned count.

Member vs operator roles

A practical split worth understanding:

• Operator roles are for the people who run the system — staff, partners, customers, suppliers. They typically grant broad "manage" and "read all" permissions and use the Internal Users (or partner/customer/supplier) context.
• Member roles are for end users of the member portal. They use the Member context and grant narrow, self-scoped permissions — for example members:read:own or members:read:own_family rather than members:read:all. The :own and :own_family resource suffixes limit a permission to the user's own record or household, which is exactly what a self-service portal user should have.

Keep these separated by context so an internal role can never accidentally be handed to a portal member, and vice versa.

How the data connects

• Users — Roles are linked to users through an assignment join (a user can have many roles, a role can have many users). The Roles list shows a live count of users per role. A role that still has users assigned cannot be deleted — reassign or remove those users first. Deleting a role is a soft delete, so historical audit records remain intact.
• The per-request RBAC gate — Every protected API call is checked against the caller's permissions. The gate first asks "does this user have admin:full:access?" — if yes, it lets the request straight through. Otherwise it checks whether the user holds the specific permission(s) the endpoint requires. The portal mirrors this in the UI by hiding buttons and screens a user lacks permission for, but the API is the real enforcement point. Changes to a role take effect after its cached permissions are refreshed.
• Member portal — Roles in the Member context flow through to the member-facing app, controlling what members can see and do there.

Permissions & access

admin:full:access satisfies all of the above. The permissions offered when building a role are limited to your tenant's licensed modules.

Tips & gotchas

• admin:full:access is a complete bypass. A user with this permission passes every access check without the specific permission ever being looked at. Grant it sparingly, to a small number of trusted administrators, and review who has it periodically.
• Permissions are OR-matched, not AND-matched. When an endpoint accepts several permissions, holding any one of them is enough — the user does not need all of them. Likewise, a user's roles combine: their effective access is the union of every permission across all their roles.
• Naming matters. Role names must be unique and are limited to 50 characters. Pick names that describe the job, not the person.
• You can't delete a role that's in use. Move its users to another role first; the count on the role detail page tells you how many are attached.
• Context mismatches block assignment. If a role won't appear when assigning it to a user, check that the role's Applicable Contexts include that user's context (e.g. a member-portal user needs a role with the Member context ticked).
• Full Access clears your other selections. If you tick Administrator Full Access by mistake, untick it before saving — your individually chosen permissions were cleared when it was switched on and will need to be re-selected.