Glossary
Quick definitions of key terms
Setup & configuration
ERPNext permissions without the guesswork
Role permissions, user permissions, permission levels and sharing are four different mechanisms answering four different questions. Most access problems come from using one to do another's job.
How do permissions work in ERPNext?
Role permissions decide which document types a role can act on. User permissions restrict which records of that type a specific user sees. Permission levels hide individual fields within a document. Sharing grants access to one record regardless of the rules. Access is the sum of a user's roles, so adding a role can only widen access, never narrow it.
Before you start
- An agreed list of job functionsDesign around what people do, not around individuals. Roles outlive the person currently doing the job.
- System Manager accessNeeded to open the Role Permissions Manager and edit user records.
- A test user per roleThe only reliable way to check a permission is to log in as someone who has it.
- Company and territory structure settledUser permissions often key off these, so changing them later means revisiting access.
Build order
Write down what each function must not see
Start from the restrictions, because permissive defaults are easy and the exclusions are what you are actually designing. Payroll, margin and supplier pricing are the usual three.
Create roles for functions, not for people
A role named after a person becomes wrong the moment they change job. Name roles for what they permit — Purchase Approver, Stock Entry Clerk.
Where Users and Permissions > Role
Set role permissions per document type
For each role decide read, write, create, submit, cancel and amend separately. Submit and cancel are the meaningful controls in an approval workflow; read and write alone rarely express what you intend.
Where Users and Permissions > Role Permissions Manager
Use permission levels for fields, not documents
When one role should see a document but not one field on it, raise that field to a higher permission level and grant the level only to roles that should read it. This is how you show a purchase order without showing its cost.
Level 0 is the document itself. Levels 1 and above are field groups you grant separately.
Apply user permissions for record-level scope
To limit someone to one company, warehouse or territory, set a user permission on their user record. This filters which records they see, and it is the mechanism people most often try to replicate with roles.
Where Users and Permissions > User Permissions
Bundle roles into role profiles
Once the set is stable, group the roles a job needs into a role profile and assign that. Onboarding then means one selection rather than fifteen checkboxes, and the fifteen stay consistent between people.
Test by logging in, not by reading the matrix
Use a test user for each profile and attempt the things that should fail. The permission matrix describes intent; the login shows behaviour.
Common mistakes
Expecting a role to remove access
Permissions are additive across roles. If a user can see something they should not, the cause is another role they hold, not a missing restriction on this one.
Using roles to limit records
Creating a role per branch to keep branches apart produces an unmanageable matrix. That is what user permissions exist for.
Leaving System Manager attached
System Manager overrides most restrictions. Testing while holding it shows you a permission model that does not exist for anyone else.
Designing so tightly that people share logins
Access that blocks legitimate work gets routed around, and a shared login destroys the audit trail the permissions were protecting.
How to check the model holds
- Log in as a test user for each role profile and confirm the navigation shows only what it should.
- Attempt one action per role that must fail, and confirm it fails with a permission message rather than succeeding quietly.
- Open a document containing a restricted field as a role that should not see it, and confirm the field is absent rather than empty.
- Confirm no ordinary user holds System Manager.
- Have one person from each function do a normal day's work in the test environment and report anything they could not complete.
Questions people ask
Almost always another role. Open the user, list every role they hold, and check each one against the document type. Access is the union of all of them, so the widest role wins.
A role permission answers whether this kind of user may act on this type of document. A user permission answers which specific records of that type this individual may see. You usually need both.
Yes, using permission levels. Raise the field above level 0 and grant the higher level only to the roles that should read it. Applied to fields, not to whole documents.
Document-level permissions apply throughout, including the REST API. Query reports can bypass expectations if written carelessly, so treat any custom report that reads restricted data as part of the permission design.
Related guides
Access model not behaving the way you designed it?
Nearly every case comes down to additive roles or the wrong mechanism for the job. Describe what a user can see that they should not, and we will tell you which layer to look at.
Ask about permissions