Roles and permissions
Control what team members and API keys can access with granular, role-based permissions.
Roles define what a user or API key can see and do in OpenMRP. Each role is a named set of permissions that controls create, read, update, and delete access across every area of the system. Roles are managed from the Roles page. Listing, creating, editing, and deleting roles is gated on the roles permission, which admins hold implicitly — so you can delegate role management to a custom role.
Why roles matter
- Security: restrict access to sensitive areas like billing, API keys, and team management
- Simplicity: assign one role per user instead of configuring individual permissions
- Consistency: the same role system applies to both team members and API keys
Built-in roles
OpenMRP ships a small number of global roles. They are shared across OpenMRP rather than owned by your account, so they show up in your roles list but cannot be renamed, edited, or deleted:
- Admin: full access to every feature, setting, and management capability
- Customer: the role assigned to customer portal users, granting the narrow set of permissions the portal needs
Admin is more than a role with every box ticked. The admin role type bypasses permission checks outright, and a few areas require it and cannot be delegated to a custom role no matter how it is configured: API keys, plan and billing changes, and connecting integrations.
Everything else is a custom role you create.
Custom roles
Create a custom role when the built-in roles don't match your needs:
- Navigate to the Roles page
- Click Create
- Enter a role name (e.g., "Sales Manager", "Warehouse Staff")
- Configure CRUD permissions for each domain
A role cannot be deleted while it is still assigned to a team member. Reassign everyone who holds it first.
Permission domains
Permissions are organized by domain. Each domain supports up to four operations: create, read, update, and delete, and a permission is written as domain:action — sales_orders:read, messaging:create, and so on. The role editor lists the domains under group headings with a checkbox per action, a Select All toggle for the whole set, and a filter box that matches on either a domain's display name or its code.
The table below is the complete set of domains a role can grant. The Area column groups them by the part of the product they cover, which is a reading aid here rather than the exact section headings you'll see in the role editor.
| Area | Domains |
|---|---|
| Account & administration | self, accounts, roles, permissions, api_keys, sandboxes, integrations, system_properties, priorities |
| Team & agents | team, departments, agents, agent_runs, agent_memories |
| Communication | messaging, alerts, email_logs |
| Customers | customers, customer_groups, contacts, addresses |
| Items & products | items, item_categories, products, product_groups, product_lines, product_types, product_variations, relevant_products, materials, parts, supplies, properties, units, unit_groups |
| Sales | sales_orders, discounts, payment_terms, sales_rep_territories, sales_targets |
| Purchasing | purchase_orders, suppliers, receiving, receiving_orders |
| Production | production_runs, production_steps, production_step_transformations, batches, shifts, scanners |
| Plant & scheduling | machines, machine_downtime, production_schedules, demand_overrides |
| Inventory | inventory, locations, adjustment_types |
| Picking & shipping | picks, department_picks, shipments, shipping_cases, shipping_terms, carriers, deliveries |
| Financial | invoices, transactions, settlements |
| Logs & auditing | audit_events, request_logs, error_logs, inventory_logs, inventory_change_logs, scanning_error_logs |
| EDI | edi_locations, edi_runs |
Two of these are easy to overlook when you build a custom role:
messaginggates almost the whole communication surface — conversations, messages and drafts, message attachments, messaging groups, blocked contacts, announcements, and the email inbox and domain settings. A role that can read sales orders but has nomessaging:readwill find those screens and endpoints returning permission errors.alertsgates sending notifications.alerts:createis what lets a user or integration push a notification to someone.
api_keys is a special case: the domain exists, but API key management is gated on the admin role type rather than on the permission, so ticking api_keys on a custom role does not let that role create or revoke keys.
Route access preview
When editing a role, OpenMRP shows a live preview of which dashboard pages the role grants access to. This helps you verify that a role provides the right level of access before assigning it.
Where roles are used
Roles apply in two places:
- Team members: assigned when inviting or editing a user
- API keys: assigned when creating an API key, controlling which API endpoints the key can call
Next: Integrations