Roles & Permissions (RBAC)

Who can see and do what in your instance is decided by roles and permissions (role-based access control, RBAC).

What It Does

An administrator shapes access on three screens under Administration: Roles, Groups and Access Control. The diagram shows how a permission, a role and a group fit together.

How Access Is Decided

A person’s effective permissions are everything granted by the roles they hold directly, plus the roles they inherit from the groups they are in, combined with any direct grants made to them individually. Roles are the normal path; a direct grant is the exception you make for one person without inventing a new role.

A group is a set of people. A role can be attached to a group, and every member then holds that role for as long as they are in the group (resolved live from group membership, not copied onto the person). A group also carries an MFA policy. A persona is a provisioning template for a job function, and it can optionally list Zonitix groups and roles. When the persona is applied — on user creation, onboarding or a role change — the person is added to those groups and roles, on top of the baseline. The same limit applies as everywhere else: an administrator cannot use a persona to give access they do not hold themselves.

If something here is not working as you expect, start with When something goes wrong.

Built-In Roles

Setup seeds these. They are ordinary roles — rename them, change their permissions, or ignore them and build your own.

Operating RBAC — The API

Everything above is the model; this section is how you actually change it. Every route below is served by the user-management service behind the gateway, so the public path is prefixed /api/v1/user-management and every call needs a valid session (Authorization: Bearer <jwt>) that carries the listed permission. There is no separate RBAC console API — these are the same endpoints the dashboard’s Roles, Groups and Permissions screens call. Two things hold across all of them: writes replace, they do not merge (userIds, groupIds and permissionIds set the entire membership, group binding or permission set, so anything in a list you send that you omit is removed), and the subset invariant in its own section below gates every grant.

Roles

name is the only required field on create (it is unique and non-null); description, userIds, groupIds and permissionIds are optional. groupIds attaches the role to groups: every member of an attached group holds the role while they are in it (the dashboard calls this Assign to Groups). Like the other lists it is a full replacement, and GET /roles returns the current binding as Groups. Create returns 201 with the new role, update returns 200, delete returns 204, and POST /:roleId/permissions returns 200 { "ok": true }. A missing role is 404. A missing or blank name is 400 (Role name is required. on create, Role name cannot be blank. on update), and a name that is already in use is 409. The administrator role is special on every path: only a caller who already holds administrator may create it, rename into or out of it, change its membership (logged ADMIN_ROLE_MEMBERSHIP_CHANGED at critical severity), or change the groups attached to it (logged ADMIN_ROLE_GROUPS_CHANGED at critical severity, since every member of an attached group becomes an administrator); it always holds the entire catalog and cannot be deleted. A change that would leave it with no member, or remove the primary administrator or the caller from it, is refused with 403 and logged ADMIN_ROLE_LOCKOUT_BLOCKED (see the subset invariant below).

The Permission Catalog & Per-User Direct Grants

GET /permissions is deliberately not readable by the baseline view_dashboard role: it returns the list of who holds manage_security, pay_invoice and the rest — a social-engineering target list — so it is gated to RBAC admins. A user’s own effective access is derived from their JWT, not from this endpoint. POST /:id/assignments is the per-user direct-grant path: userIds writes rows straight into the user’s effective permissions (these land in the JWT), and roleIds writes the same role↔permission rows from the other side. Both are optional but both are full replacements of that permission’s user set and role set respectively — and the administrator role is always re-added afterwards, so it can never be stripped of a permission this way. Returns 200 { "ok": true }, or 404 if the permission id does not exist.

Groups & MFA Policy

Groups organise people, pass on any role attached to them (see Roles above), and carry an MFA policy. The policy is the three-way mfaPolicy: inherit (follow the organisation-wide setting), require (every member must use MFA) or exempt. An exemption takes two more fields: mfaExemptUntil (an ISO date, or null for no end date) and mfaExemptReason; both are cleared when the policy leaves exempt. The older boolean requiresMfa is still accepted when mfaPolicy is not sent (true maps to require, false to inherit) and is kept mirrored on the group.

Writable fields are allow-listed — name, description, userIds — and the MFA fields are only honoured for a caller who also holds manage_security. A policy change is audited as its own event: MFA_EXEMPTION_GRANTED and MFA_EXEMPTION_REVOKED at warning severity, and MFA_POLICY_CHANGED (info) for a move between inherit and require. Create returns 201, update 200, delete 204; a missing group is 404 and a name that is already in use is 409. A membership change on a group that confers permissions the caller does not hold is 403 (see the subset invariant below). Deleting a group is audited as GROUP_DELETED at warning severity.

Scoped Compliance Access

These two are a narrow, fixed grant: they can only ever add or remove the single view_assigned_compliance permission (a direct user grant, so it touches only that one person), used when an auditor assigns or finalizes a compliance section. There is no body — the target is the :userId in the path. A missing user is 404; if view_assigned_compliance was never seeded, grant returns 400. Success is 200 { "ok": true }, logged COMPLIANCE_ACCESS_GRANTED / COMPLIANCE_ACCESS_REVOKED.

The Subset Invariant: You Cannot Confer What You Do Not Hold

This is the single most important control on the RBAC surface, and it is worth stating plainly because an earlier version of it failed by guarding one door of several. A non-administrator caller can never grant a permission they do not themselves hold — not by creating a role that carries it, not by editing a role into carrying it, not by replacing a role’s permission set, and not by assigning the permission from the permission side. The caller’s held set is resolved from the database (their roles’ permissions plus their own direct grants), never from the request header, because the gateway scopes that header per service. An administrator bypasses the check by design (it is root and holds everything), and an unidentifiable caller fails closed — it may grant nothing.

Seeded Permission Catalog

Every atomic permission the platform seeds, straight from the canonical catalog the installer and the on-boot reconciler both read. It is the full set a role’s permissionIds can draw from.