Custom Permissions
Custom Permissions in Salesforce are admin-defined boolean permissions that exist alongside the platform's standard CRUD and field-level permissions.
Definition
Custom Permissions in Salesforce are admin-defined boolean permissions that exist alongside the platform's standard CRUD and field-level permissions. Each Custom Permission has a name, a label, an optional description, and a connection to permission sets and profiles. Code (Apex, Flow, Lightning Components) can check whether the running user has a specific Custom Permission and branch behavior accordingly. The construct exists to let admins gate custom code paths and configuration through the same permission-set assignment mechanism users already understand.
Custom Permissions exist because some business logic does not fit cleanly into CRUD permissions. A user might need to approve renewals at one tier but not another; an Apex trigger should fire for some users and not others; a Flow should branch based on whether the running user is a regional manager or a regional director. Hardcoding these distinctions in code with profile or role name checks is brittle; using Custom Permissions lets the access decision live in permission set assignment where admins can see and audit it.
Why Custom Permissions move business-logic gates out of code and into admin-managed assignment
Where Custom Permissions live and how they are created
Setup, Custom Code, Custom Permissions. The page lists existing Custom Permissions. New Custom Permission opens a form for label, name (API identifier), description, and optional Connected App (rarely used; legacy). Saving creates the Custom Permission record. The Custom Permission then needs to be assigned to users through permission sets (Setup, Permission Sets, pick the set, System Permissions, Custom Permissions section). Without assignment, no user holds the permission.
Checking Custom Permissions in code
Apex: FeatureManagement.checkPermission(''My_Custom_Permission'') returns true if the running user has it. LWC: import hasPermission from @salesforce/customPermission/My_Custom_Permission, returns true or false. Flow: a {!$Permission.My_Custom_Permission} reference in any decision or formula. Validation Rule: $Permission.My_Custom_Permission for inclusion or exclusion. The pattern is consistent: code checks the permission, the admin controls assignment, the business logic gate is configurable without redeploying code.
Permission sets and the assignment model
Custom Permissions are assigned through permission sets, not profiles directly. Users who hold a permission set containing a Custom Permission have that permission; users without the permission set do not. The right pattern: name permission sets after the business role (Renewal Manager, Regional Director, Senior Banker), include the Custom Permissions that role needs, assign the permission set to the right users. Profile-based assignment is technically possible but breaks the modern Salesforce-recommended permission-set-first pattern.
Common use cases
Five recur. Validation rule bypass (Custom Permission Bypass_Discount_Validation lets specific users save records that violate the discount validation rule, without removing the validation for everyone). Flow branching (Custom Permission Senior_Approver routes approval Flows to the senior path). Apex trigger gating (Custom Permission Skip_Recalculation lets bulk integrations bypass expensive triggers). Lightning Component visibility (Custom Permission Show_Beta_Section hides a component from users without the permission). External access gating (Custom Permission Access_Internal_API gates a custom API endpoint).
Custom Permission vs Permission Set vs Profile permission
Standard permissions (View All Data, Modify All Data, API Enabled) and CRUD permissions live in profiles and permission sets directly. Custom Permissions sit alongside as a separate construct admins create and code references. The right tool depends on whether the platform already has a permission for the use case. Restricting object create access: use Object Permissions. Gating a custom Apex method: Custom Permission. Restricting field visibility: Field-Level Security. Pick the platform-native construct when it exists; reach for Custom Permissions when no platform construct matches.
Audit, documentation, and the inventory question
Custom Permissions accumulate. A typical mature org holds dozens to hundreds. Without documentation, the meaning of each permission gets lost over time; new admins do not know whether Bypass_Discount_Validation should be granted broadly or kept narrow. The discipline: document each Custom Permission with its purpose, the code paths that check it, the permission sets that include it, the user populations that hold it. The inventory is what saves future admins from playing forensics.
Performance and the check-cost question
Custom Permission checks are fast. The FeatureManagement.checkPermission call is cached per transaction; checking the same permission ten times within one Apex execution is one underlying lookup. LWC and Flow checks have similar caching. The performance cost is negligible compared to the alternative (querying PermissionSetAssignment and PermissionSetCustomPermission directly), so admins should use the FeatureManagement API or the platform-native constructs rather than rolling their own.
How to use Custom Permissions for code-gated business logic
The pattern: identify the business-logic gate, create the Custom Permission, reference it in code, assign through a permission set named after the role. The cost is one Custom Permission record plus one code reference; the benefit is admin-managed access without redeploying code for assignment changes.
- Identify the business-logic gate that needs admin-controlled access
A validation rule that should bypass for certain users, a Flow that should branch for senior approvers, an Apex method that should run for specific roles. The candidate is any access decision currently hardcoded.
- Create the Custom Permission
Setup, Custom Permissions, New. Name per convention (purpose-driven: Bypass_Discount_Validation, Senior_Approver, Access_Beta_Feature).
- Reference the Custom Permission in code
Apex: FeatureManagement.checkPermission. LWC: import from @salesforce/customPermission. Flow: $Permission reference. Validation Rule: $Permission reference.
- Create or extend a permission set with the Custom Permission
Name the permission set after the business role (Renewal Manager, Senior Approver). Include the Custom Permission in the set's System Permissions, Custom Permissions section.
- Assign the permission set to the right user population
Bulk assign via Setup or via a Flow that triggers on user attribute changes. Document the assignment criteria.
- Test with users in and out of the assigned population
Confirm the code path fires for assigned users and skips for unassigned. Sandbox first; production behavior should match.
- Document the Custom Permission and code references
Name, purpose, code references, permission sets that include it. The inventory is what saves future admins from forensics.
Purpose-driven, convention-based. The API identifier code references.
Permission set named after business role; includes one or more related Custom Permissions.
Apex FeatureManagement.checkPermission, LWC import, Flow $Permission, Validation Rule $Permission.
Name, purpose, code references, holding permission sets. Required for maintainability.
Test both with and without the permission to confirm the code branches correctly.
- Custom Permissions assigned through profiles work but break the modern permission-set-first pattern. Default to permission-set assignment.
- Without assignment, no user holds the Custom Permission. Creating the Custom Permission and forgetting the permission set assignment is a common omission.
- Code that checks a Custom Permission and finds nobody has it executes the no-permission branch. Test both branches; the unassigned branch needs to be correct, not just the assigned one.
- Custom Permissions accumulate without documentation. The inventory is the discipline that prevents permission sprawl.
- Pick platform-native permissions when they exist. Custom Permissions are the right tool when no platform construct fits; using them for things the platform already supports adds unnecessary configuration.
Trust & references
Cross-checked against the following references.
- Custom Permissions referenceSalesforce
- Permission Sets referenceSalesforce
Straight from the source - Salesforce's reference material on Custom Permissions.
- Custom PermissionsSalesforce Help
- FeatureManagement ClassSalesforce Developers
- Permission SetsSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. Why is understanding Custom Permissions important for Salesforce admins?
Q2. Can a Salesforce admin configure Custom Permissions without writing code?
Q3. In which area of Salesforce would you typically find Custom Permissions?
Discussion
Loading discussion…