ERPNext Permissions Skill

Deterministic patterns for implementing robust permission systems in Frappe/ERPNext applications.

---

Overview

Frappe's permission system has five layers:

Layer	Controls	Configured Via	Version
Role Permissions	What users CAN do	DocType permissions table	All
User Permissions	WHICH documents users see	User Permission records	All
Perm Levels	WHICH fields users see	Field permlevel property	All
Permission Hooks	Custom logic	hooks.py	All
Data Masking	MASKED field values	Field mask property	v16+

---

Quick Reference

Permission Types

Type	Check	For
read	frappe.has_permission(dt, "read")	View document
write	frappe.has_permission(dt, "write")	Edit document
create	frappe.has_permission(dt, "create")	Create new
delete	frappe.has_permission(dt, "delete")	Delete
submit	frappe.has_permission(dt, "submit")	Submit (submittable only)
cancel	frappe.has_permission(dt, "cancel")	Cancel
select	frappe.has_permission(dt, "select")	Select in Link (v14+)
mask	Role permission for unmasked view	View unmasked data (v16+)

Automatic Roles

Role	Assigned To
Guest	Everyone (including anonymous)
All	All registered users
Administrator	Only Administrator user
Desk User	System Users (v15+)

---

Essential API

Check Permission

# DocType level
frappe.has_permission("Sales Order", "write")

# Document level
frappe.has_permission("Sales Order", "write", "SO-00001")
frappe.has_permission("Sales Order", "write", doc=doc)

# For specific user
frappe.has_permission("Sales Order", "read", user="john@example.com")

# Throw on denial
frappe.has_permission("Sales Order", "delete", throw=True)

# On document instance
doc = frappe.get_doc("Sales Order", "SO-00001")
if doc.has_permission("write"):
    doc.status = "Approved"
    doc.save()

# Raise error if no permission
doc.check_permission("write")

Get Permissions

from frappe.permissions import get_doc_permissions

# Get all permissions for document
perms = get_doc_permissions(doc)
# {'read': 1, 'write': 1, 'create': 0, 'delete': 0, ...}

User Permissions

from frappe.permissions import add_user_permission, remove_user_permission

# Restrict user to specific company
add_user_permission(
    doctype="Company",
    name="My Company",
    user="john@example.com",
    is_default=1
)

# Remove restriction
remove_user_permission("Company", "My Company", "john@example.com")

# Get user's permissions
from frappe.permissions import get_user_permissions
perms = get_user_permissions("john@example.com")

Sharing

from frappe.share import add as add_share

# Share document with user
add_share(
    doctype="Sales Order",
    name="SO-00001",
    user="jane@example.com",
    read=1,
    write=1
)

---

Data Masking (v16+)

Data Masking protects sensitive field values while keeping fields visible. Users without mask permission see masked values (e.g., ****, +91-811XXXXXXX).

Use Cases

• HR: Show employee details but mask salary amounts
• Support: Show phone numbers partially masked
• Finance: Show bank account fields without full numbers

Enable Data Masking

Via DocType (Developer Mode) or Customize Form:

{
  "fieldname": "phone_number",
  "fieldtype": "Data",
  "options": "Phone",
  "mask": 1
}

Supported Field Types:

• Data, Date, Datetime
• Currency, Float, Int, Percent
• Phone, Password
• Link, Dynamic Link
• Select, Read Only, Duration

Configure Permission

Add mask permission to roles that should see unmasked data:

{
  "permissions": [
    {"role": "Employee", "permlevel": 0, "read": 1},
    {"role": "HR Manager", "permlevel": 0, "read": 1, "mask": 1}
  ]
}

How It Works

┌─────────────────────────────────────────────────────────────────────┐
│ DATA MASKING FLOW                                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  1. Field has mask=1 in DocField configuration                      │
│                                                                     │
│  2. System checks: meta.has_permlevel_access_to(                    │
│        fieldname=df.fieldname,                                      │
│        df=df,                                                       │
│        permission_type="mask"                                       │
│     )                                                               │
│                                                                     │
│  3. If user LACKS mask permission:                                  │
│     └─► Value automatically masked in:                              │
│         • Form views                                                │
│         • List views                                                │
│         • Report views                                              │
│         • API responses (/api/resource/, /api/method/)              │
│                                                                     │
│  4. If user HAS mask permission:                                    │
│     └─► Full value displayed                                        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

⚠️ Critical: Custom SQL Queries

Data Masking does NOT apply to:

• Custom SQL queries
• Query Reports using raw SQL
• Direct frappe.db.sql() calls

You must implement masking manually:

def get_customer_report(filters):
    data = frappe.db.sql("""
        SELECT name, phone, email FROM tabCustomer
    """, as_dict=True)
    
    # Manual masking for users without permission
    if not frappe.has_permission("Customer", "mask"):
        for row in data:
            if row.phone:
                row.phone = mask_phone(row.phone)
    
    return data

def mask_phone(phone):
    """Mask phone number: +91-81123XXXXX"""
    if len(phone) > 5:
        return phone[:6] + "X" * (len(phone) - 6)
    return "****"

---

Permission Hooks

has_permission Hook

Add custom permission logic. Can only deny, not grant.

# hooks.py
has_permission = {
    "Sales Order": "myapp.permissions.check_order_permission"
}

# myapp/permissions.py
def check_order_permission(doc, ptype, user):
    """
    Returns:
        None: Continue standard checks
        False: Deny permission
    """
    # Deny editing cancelled orders for non-managers
    if ptype == "write" and doc.docstatus == 2:
        if "Sales Manager" not in frappe.get_roles(user):
            return False
    
    return None  # ALWAYS return None by default

permission_query_conditions Hook

Filter list queries. Only affects get_list(), NOT get_all().

# hooks.py
permission_query_conditions = {
    "Customer": "myapp.permissions.customer_query"
}

# myapp/permissions.py
def customer_query(user):
    """Return SQL WHERE clause fragment."""
    if not user:
        user = frappe.session.user
    
    # Managers see all
    if "Sales Manager" in frappe.get_roles(user):
        return ""
    
    # Others see only their customers
    return f"`tabCustomer`.owner = {frappe.db.escape(user)}"

CRITICAL: Always use frappe.db.escape() - never string concatenation!

---

get_list vs get_all

Method	User Permissions	Query Hook
frappe.get_list()	✅ Applied	✅ Applied
frappe.get_all()	❌ Ignored	❌ Ignored

# User-facing query - respects permissions
docs = frappe.get_list("Sales Order", filters={"status": "Open"})

# System query - bypasses permissions
docs = frappe.get_all("Sales Order", filters={"status": "Open"})

---

Field-Level Permissions (Perm Levels)

Configure Field

{
  "fieldname": "salary",
  "fieldtype": "Currency",
  "permlevel": 1
}

Configure Role Access

{
  "permissions": [
    {"role": "Employee", "permlevel": 0, "read": 1},
    {"role": "HR Manager", "permlevel": 0, "read": 1, "write": 1},
    {"role": "HR Manager", "permlevel": 1, "read": 1, "write": 1}
  ]
}

Rule: Level 0 MUST be granted before higher levels.

---

Decision Tree

Need to control access?
├── To entire DocType → Role Permissions
├── To specific documents → User Permissions
├── To specific fields (hide completely) → Perm Levels
├── To specific fields (show masked) → Data Masking (v16+)
├── With custom logic → has_permission hook
└── For list queries → permission_query_conditions hook

Checking permissions in code?
├── Before action → frappe.has_permission() or doc.has_permission()
├── Raise error → doc.check_permission() or throw=True
└── Bypass needed → doc.flags.ignore_permissions = True (document why!)

---

Common Patterns

Owner-Only Edit

{
  "role": "Sales User",
  "read": 1, "write": 1, "create": 1,
  "if_owner": 1
}

Check Before Action

@frappe.whitelist()
def approve_order(order_name):
    doc = frappe.get_doc("Sales Order", order_name)
    
    if not doc.has_permission("write"):
        frappe.throw(_("No permission"), frappe.PermissionError)
    
    doc.status = "Approved"
    doc.save()

Role-Restricted Endpoint

@frappe.whitelist()
def sensitive_action():
    frappe.only_for(["Manager", "Administrator"])
    # Only reaches here if user has role

---

Critical Rules

1. ALWAYS use permission API - Not role checks
2. ALWAYS escape SQL - frappe.db.escape(user)
3. ALWAYS use get_list - For user-facing queries
4. ALWAYS return None - In has_permission hooks (not True)
5. ALWAYS document - When using ignore_permissions
6. ALWAYS clear cache - After permission changes: frappe.clear_cache()
7. ALWAYS mask manually - In custom SQL queries (v16+)

---

Anti-Patterns

❌ Don't	✅ Do
if "Role" in frappe.get_roles()	frappe.has_permission(dt, ptype)
frappe.get_all() for user queries	frappe.get_list()
return True in has_permission	return None
f"owner = '{user}'"	f"owner = {frappe.db.escape(user)}"
frappe.throw() in hooks	return False
Assume masking in custom SQL	Implement masking manually

---

Version Differences

Feature	v14	v15	v16
select permission	✅	✅	✅
Desk User role	❌	✅	✅
Custom Permission Types	❌	❌	✅ (experimental)
Data Masking	❌	❌	✅
mask permission type	❌	❌	✅

---

Debugging

# Enable debug output
frappe.has_permission("Sales Order", "read", doc, debug=True)

# View logs
print(frappe.local.permission_debug_log)

# Check user's effective permissions
from frappe.permissions import get_doc_permissions
perms = get_doc_permissions(doc, user="john@example.com")

---

Reference Files

See references/ folder for:

• permission-types-reference.md - All permission types
• permission-api-reference.md - Complete API reference
• permission-hooks-reference.md - Hook patterns
• examples.md - Working examples
• anti-patterns.md - Common mistakes

---

Related Skills

• erpnext-database - Database operations that respect permissions
• erpnext-syntax-controllers - Controller permission checks
• erpnext-syntax-hooks - Hook configuration

---

Last updated: 2026-01-18 | Frappe v14/v15/v16