Users, roles, and permissions

Mosce ERP combines three concepts: users (the people), roles (permission bundles), and individual permissions (module:action). This guide explains how to invite, what role to give each person, and how to build custom roles.

Reading time: ~8 min

When to use this

• You're about to add someone to the tenant (salesperson, cashier, accountant, partner).
• You need a user to be able to perform a specific action and you don't know which permission to enable.
• You want to create a custom role that doesn't fit the system roles.
• You have to remove someone who no longer works with you.

Before you start

• You need one of these permissions depending on the action:
  • users:invite to invite.
  • users:update to activate/deactivate.
  • users:assign-role to change the membership role (ADMIN/MEMBER).
  • roles:manage to create, edit, or delete custom roles.
• The tenant's email provider must be configured, because the invitation is sent by email. If it isn't, you'll see an Integration not configured toast; go to Settings › Integrations first.

Key concepts

Users

A person with an account in Mosce ERP who belongs to your tenant through a membership. Each membership has:

• A membership role at the tenant level: OWNER, ADMIN, or MEMBER.
• Zero or more roles (the ones that appear in Settings › Roles) that provide fine-grained permissions.
• An active / inactive status. Inactive = cannot sign in, but the account and its history are preserved.

OWNER bypasses all permission checks (full access to your account, regardless of what permissions their role has). ADMIN does not bypass: it simply has almost all permissions assigned by default in its role template - the assignment is explicit, so if you remove a permission from the Administrator role, that user stops having it. MEMBER can only do what their roles allow.

Roles

A role is a named bundle. There are two types:

• System roles - created automatically when the tenant is provisioned. They cannot be edited or deleted; you recognize them by the System label.
• Custom roles - the ones you create. You can edit and delete them. If a custom role has users assigned, you can't delete it: remove it from those users first.

System roles

Owner works with a full bypass (it needs no assigned permissions). Administrator ships with all relevant permissions by default in its template, so in practice it can do everything - but the assignment is explicit and you can audit it in Settings › Roles. The rest of the roles come with a more limited base set, also auditable on the same screen.

Permissions

A permission is an atomic capability with the format resource:action. For example:

• invoices:create - create invoices.
• inventory:adjust - make inventory adjustments.
• fiscal:read / fiscal:manage - view or manage the fiscal module.
• roles:manage, users:invite, modules:manage - tenant administration.

The full catalog is grouped by resource (invoices, products, inventory, accounting, fiscal, reports, etc.) and is shown inside the form of a custom role.

Purchase permissions - granular by action

The purchases module separates each action into its own permission, so you can, for example, let a warehouse worker receive goods without being able to send orders to the supplier, or let a buyer create and send orders but not cancel them.

The purchases:manage permission is kept as a legacy permission so as not to break old roles that had it: it groups the ability to send and cancel. New roles should use the granular permissions (purchases:send, purchases:cancel). The Manager role already includes the new permissions, so existing managers keep their capability unchanged.

See the full flow in Purchases.

Advanced fiscal permissions - contingency and replacements

The following permissions are relevant if you have users with the MEMBER role who need to manage contingency episodes or issue replacement e-CFs. OWNER and ADMIN have them by default.

To create an external accountant role with access to contingency and replacements, for example, you would enable fiscal:read, fiscal:contingency:declare, and fiscal:replacement:create. Reserve fiscal:past-sla:decide and fiscal:replacement:override-window for those who have the fiscal authority for those decisions.

Dashboard permissions

The following permissions control which sections of the main dashboard each user can see. You'll find them in the form of any custom role, just like the rest of the catalog.

Each permission unlocks exactly one section: if the user doesn't have the permission, that section doesn't appear on their dashboard and generates no request to the server (it's not just visually hidden). The dashboard also includes a period selector with four options - current month (default), last month, quarter, or year - that applies to all sections the user is authorized for.

By default, Owner and Administrator already have them (the first through full access, the second because they come included in its default configuration). The operational roles (Manager, Salesperson, Cashier, Viewer) don't come with them out of the box: your account administrator assigns them from Settings › Roles based on who needs to see each section.

Audit log permissions

The following permissions control access to the audit log viewer. They are available only on the Starter plan or higher; on the free plan the viewer is not shown even if the user has the permission assigned.

Owner has full access by design. Administrator has audit:read included in its default configuration. The rest of the roles don't come with them out of the box.

See Audit log to understand what the log contains and how to use it.

Step by step: invite a user

1. Go to Settings › Users and click Invite user.
2. Fill in:
   • The invitee's Email.
   • Role (one of the system roles or a custom one) - this provides the fine-grained permissions.
   • Membership role: ADMIN (full access) or MEMBER (only what the role allows).
3. Click Send. The person receives an email with a link to accept the invitation and create their password.
4. On acceptance, they appear in the users table as active.

Step by step: change the membership role or deactivate

In the Settings › Users table, the Actions column of each row gives you:

• Change role - opens a dialog to switch between ADMIN and MEMBER.
• Deactivate / Activate - blocks or restores access.

You can't edit yourself (you'll see a You marker instead of the buttons), and you can't deactivate the last owner of the tenant: the API responds with the Last owner protected error.

Step by step: create a custom role

1. Go to Settings › Roles and click New role.
2. Give it a name (for example External accountant) and optionally a description.
3. Check the permissions in the matrix, grouped by resource. Each permission shows its slug and, where applicable, a short description.
4. Save. The role appears in the Custom roles section and is now available on the invitation screen and in Change role.

To adjust permissions later, open the role with the pencil icon and save again. To delete it, use the trash icon (it doesn't work if it has users assigned).

Expected result

• The invitee receives an email and, after accepting it, can sign in and see only what their role allows.
• In the Users table, active members have a green dot and inactive ones a gray dot.
• Custom roles coexist with system roles. A user can have several roles at once: their effective permissions are the union of all of them.

Common mistakes

• The invitation email doesn't arrive. Check that the tenant's email provider is configured in Settings › Integrations and that the recipient checks spam.
• I can't deactivate the owner. It's by design: at least one active owner must exist. Promote another person to owner first.
• I removed a permission from the role and the user still has access. If they have other roles assigned that also include that permission, the effect is the union. Review all of the user's roles.
• I enabled a permission but the user sees "Insufficient permission". Ask them to sign out and back in; permissions travel in the JWT and refresh at sign-in.
• I deleted a role and left users with no permissions. You can only delete custom roles with no users assigned; if you reached this state, recreate the role and assign it, or assign a different one to those users.

Related

• Dashboard - description of each dashboard section and how to interpret the metrics.
• Modules - which modules are on and, therefore, which permissions have real effect.
• Billing and subscription - the plan sets the maximum number of users.
• General settings - tenant data seen by all users.
• Purchases - where the purchases:* permissions apply.