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 anything: it can only do what its roles grant, exactly like MEMBER. The difference between the two is in membership administration, not in privileged access to the data.

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

Every factory role ships with what its own work needs

A factory role arrives ready to do its job end to end. The Salesperson can quote, create the order, invoice it and read the taxes those invoices carry; the Cashier can collect and close their register. You do not have to reassemble them permission by permission before anyone can work.

It was not always this way, and the reason for the change is worth knowing because it tells you what to look for when something comes out odd: a role missing a permission does not always produce an error. Sometimes it simply produces an incomplete result. The case that exposed it was a Salesperson who could not read the configured taxes: invoicing appeared to work, and the invoices came out with no ITBIS and no warning at all.

• Owner works with full access and needs no assigned permissions.
• Administrator, Manager, Salesperson, Cashier and Viewer ship with their own operations covered, and remain auditable permission by permission in Settings › Roles.
• Factory roles fill themselves in when the application adds new permissions. You do not have to recreate roles or reassign users.
• Anything beyond that is still your call. A Salesperson sees no financial reports and no company settings because selling does not require them; if your business needs otherwise, you grant it.

A custom role is the responsibility of whoever builds it. The above covers factory roles. If you build one of your own, remember that a missing permission may not raise an error, only a half-finished result, so it is worth walking the whole flow with an account holding that role before handing it out.

A granted permission applies as soon as the person reloads the screen. No sign-out needed: permissions no longer travel inside the session, they are read from the server, so granting or removing one takes effect immediately. If somebody says "you gave it to me and I still cannot see it", ask them to reload the page. What does still need a fresh sign-in is a change of modules or plan, because those do travel in the session.

The two cash-close permissions

cash-register:view-close-amounts decides whether the amount the system expects is visible at closing time. Whoever lacks it counts blind. This is not gratuitous distrust: if the expected figure is on screen, nobody declares a number different from the one in front of them, and the count stops measuring anything. What is hidden is what the system expects, never what the person counted.

cash-register:authorize-close allows approving someone else's shift close and cash withdrawals, when the company turns that requirement on. Nobody can authorize themselves, even holding the permission.

Neither ships with the Cashier role, which is precisely the point of having them. See Cash register.

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.

Cash register and point-of-sale permissions

The factory Cashier role can now work a register end to end. A newly created cashier opens their shift, sells at the counter, collects the documents that reach the register, records movements and prints their receipts, without you configuring anything.

Where the line is. Handing money back at the register and within the shift is cashier work: it goes into the shift reconciliation and squares off at closing. Moving that same money from the back office and outside the shift is not.

Collecting and voiding a collection are two separate permissions

Voiding a payment that is already recorded has its own permission, payments:void, separate from the permission to collect (invoices:pay). It used to be enough to be able to collect: whoever recorded a payment could undo a booked one.

The reason is internal control: recording a payment is counter work; undoing a booked payment reopens the document balance and affects the shift reconciliation. Out of the box, Administrator and Manager carry it; the Cashier does not. If in your business the cashier should be able to void payments, grant it explicitly from Settings › Roles.

See Payments and payment methods.

Applying a credit balance and applying a credit note are two separate permissions

invoices:apply-customer-credit and invoices:apply-credit-note cover different money, from different origins: one pays with the balance a client is left with from a refund or an advance payment, the other pays by consuming a credit note, which is an electronic tax document. A role being able to use one does not mean it can use the other. Neither ships by default on the Cashier role.

invoices:register-advance is a separate permission again: it covers receiving money from a client before a sale exists (an advance payment), not spending it. It does not ship by default on any role except Owner either. See Clients and Payments and payment methods.

invoices:withhold-tax-override ("Decidir la Devolución del ITBIS") neither grants nor removes the ability to refund: whoever holds it can change the default of the 30-day window on a given refund, in either direction. Returning the ITBIS past the 30 days is a decision with tax consequences and it records who authorised it, which is why it sits on its own and only the Administrator role ships with it. See Refunds.

Permissions you have to grant by hand

Neither of these ships with any role out of the box, and both tend to give the impression that "the button is broken" when in fact they simply have not been granted:

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.

You do not need to configure email first. If your business has not connected its own provider yet, the invitation still goes out through the platform's email. The message always says who is inviting and to which company, so the recipient recognises it even when the sender is not your business's domain. If you connect your provider, yours is used. That fallback is for invitations only: sending quotations and invoices to customers still requires your own. See General settings.

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 assign the permission role that decides what that person can do: Manager, Salesperson, Cashier, Viewer or any custom role of yours. Requires the users:assign-role permission, and the change takes effect as soon as that person reloads the screen.
• Branches - decides which locations they can work in.
• 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 granted a permission and the user still cannot see it. Ask them to reload the page. Permissions are read from the server on every load, so there is no need to sign out.
• My cashier cannot open the register. The factory Cashier role already carries the cash shift permissions. If you assigned a custom role, grant it cash-session:open and the rest of the cash permissions table, then ask them to reload the page.
• My cashier does not see the credit balance among the payment methods, or the option to register an advance payment. Neither ships by default on the Cashier role. Grant invoices:apply-customer-credit and invoices:register-advance as needed, and ask them to reload the page.
• I cannot see the point of sale in the menu. Either pos:orders.read or pos:orders.create is missing from the user's role, or the point-of-sale module is not active on your plan. Check both: Modules first, then the role.
• I gave someone the Administrator role and they can barely do anything. That is the expected behaviour: factory roles are conservative and the Administrator starts with very few permissions. Grant what they need in Settings › Roles.
• 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.
• Payments and payment methods - what payments:void means next to invoices:pay.
• Cash register - the shift the cash-session:* permissions operate.
• Point of sale (POS) - what a cashier needs in order to work.