Roles and permissions

Permissions decide what people can see and do in Modulix: view contacts, approve expense claims, manage users. You never give permissions to people directly. You group them in roles, then give roles to people on the Users page.

Before you begin

• To see the Roles & permissions page, you need View roles (core.roles.read).
• To create, change and delete roles, you need Create and edit roles (core.roles.manage). Owners and administrators have both by default.

Key concepts

• Permission: one thing a person may do, such as View contacts and companies. Each has a key, for example contacts.contact.read. The core and every module declare their own permissions; you see those of the modules enabled for your organization.
• Role: a named set of permissions, such as Sales manager. A person can have several roles; they get every permission of all their roles together.
• System role: one of the four roles every organization starts with. They cannot be deleted.
• Record scope: for some permissions, a role can be limited to the records a person owns, or to their team's records, instead of all records.

System roles

Role	Description	Permissions
Owner	Full access to everything	Every permission, always. Cannot be changed. The person who creates an organization is its owner.
Administrator	Manages users, roles, settings and modules	All core administration permissions, plus what each module gives administrators by default (usually all of its permissions).
Member	Default role for new users	What each module gives members by default, typically the day-to-day work of that module.
Read-only	Views what members view, changes nothing	The view permissions of each module, unless the module decides otherwise, and View users.

You can change the permissions of Administrator, Member and Read-only to suit your organization. A lock icon next to their name in the list reminds you that they are system roles.

View and change a role's permissions

1. In the sidebar, under Administration, select Roles & permissions.
2. Select a role in the list on the left. Its permissions appear on the right, grouped by module.
3. Tick the permissions the role should have and untick the others. Under each permission label you see its key, for example notes.note.write.
4. To give every permission of a module, tick All module permissions next to the module's name. The role then also gets permissions the module adds in later versions.
5. Select Save. Modulix shows Permissions saved.

Editing the permissions of a custom role.

The Save button is only active once you change something. When All module permissions is ticked, the permissions of that module show as ticked and greyed out: they are already included.

People who have the role get the new permissions within a few seconds, without signing in again.

note

The Owner role cannot be edited: "Owners always have every permission." Keep at least one owner in each organization.

Create a role

1. On the Roles & permissions page, select New role.
2. Enter a Name, for example Sales manager.
3. Enter a Key, for example sales-manager. The key identifies the role in the API and in imports. Use lowercase letters, digits and hyphens, starting with a letter, 2 to 63 characters. It cannot be changed later.
4. Optionally enter a Description. It appears under the role name when you choose roles for a person.
5. Select Create. Modulix shows Role created and selects the new role.
6. Tick its permissions and select Save.

A new role starts with no permissions.

Creating a custom role.

Limit a permission to some records

Some permissions can be granted for part of the records only. When you tick one of them, a drop-down list appears next to it with three choices:

Choice	The person can act on
Their own	Records they own.
Their team’s	Records owned by them or by people of their team: people in the same organization units, and in the units below them.
All records	Every record of that type. This is the default.

For example, give a Sales rep role View contacts and companies for All records but Create and edit contacts and companies for Their own only: reps see every contact but only change their own.

Scoped permissions include, among others, those of contacts and companies, opportunities, quotations, sales orders and invoices, suppliers and purchase orders, tasks and expense claims. Modules set some scopes by default: for example, members can only edit their own tasks, and only see and edit their own expense claims.

Good to know:

• Teams come from the Organization Structure module. Without it, Their team’s covers only the person's own records.
• If a person has the same permission at different scopes through several roles, the widest scope applies.
• API keys, OAuth clients and workflows do not act as a person, so only All records applies to them.
• The drop-down list does not appear when the permission is already included by All module permissions: the role then has it for all records.

How modules add permissions to roles

When an administrator enables a module, Modulix gives its default permissions to the system roles: typically everything to Administrator, the day-to-day permissions to Member and the view permissions to Read-only. Each module's page in this documentation lists its permissions and their default roles.

• Custom roles get nothing automatically. After enabling a module, add its permissions to your custom roles.
• Disabling a module keeps the permissions in your roles; they have no effect while the module is off.
• Enabling a module again gives the default permissions again, including any you removed from a system role. Check your system roles after re-enabling a module.
• Uninstalling a module from the server removes its permissions from every role.

Delete a role

1. Select the custom role in the list.
2. Select the delete button (trash icon) at the top of the role.
3. Confirm with Delete. The dialog reminds you: "Users keep their other roles."

System roles cannot be deleted. People who only had the deleted role keep access to the organization, with no permissions until you give them another role.

When someone lacks a permission

People only see the menu entries, pages and buttons their permissions allow. If someone opens a page anyway, Modulix shows Page not found. If an action is refused, Modulix shows an error message and records the attempt in the audit log as access.denied, with who tried and what.

Role changes are also recorded in the audit log (role.created, role.updated with the permissions before and after, role.deleted).

Core permissions

The core of Modulix declares these permissions. Modules add their own; see each module's page.

Permission	What it allows	Granted by default to
core.users.read	View users	Administrator, Member, Read-only
core.users.manage	Invite, edit and remove users	Administrator
core.roles.read	View roles	Administrator
core.roles.manage	Create and edit roles	Administrator
core.settings.read	View organization settings	Administrator
core.settings.manage	Edit organization settings	Administrator
core.modules.read	View modules	Administrator
core.modules.manage	Enable and disable modules	Administrator
core.apikeys.manage	Manage API keys	Administrator
core.webhooks.manage	Manage webhooks	Administrator
core.audit.read	View audit log	Administrator
core.views.share	Share saved views with everyone	Administrator
core.data.import	Import records from files	Administrator
core.data.export	Export records to files	Administrator

The Owner role has all of them, and every module permission, through the * wildcard.

Tips

• Start from the system roles and only create custom roles when two groups of people need different access. Fewer roles are easier to review.
• To give a role broad access to one module without listing each permission, use All module permissions.
• Review roles after enabling new modules, especially custom roles, which get nothing automatically.