Custom Permissions
Custom Permissions is a Setup page where administrators create named permissions that can be assigned to users via Permission Sets or Profiles.
Definition
Custom Permissions is a Setup page where administrators create named permissions that can be assigned to users via Permission Sets or Profiles. Custom Permissions act as feature flags that developers and administrators can check in Apex code, validation rules, and Flows to control access to custom functionality without modifying profiles.
In plain English
“Here's a simple way to think about it: Custom Permissions are feature flags built into the platform. Named flags assigned via Permission Sets; checked from Apex, Flow, validation rules. The cleanest way to gate behavior without distorting security.”
Worked example
The developer at CloudBridge Solutions creates a Custom Permission called "Can_Override_Discount." She adds a check in the Apex trigger: if the current user has this permission, they can apply discounts above 30%. The admin then assigns this permission to a "Sales Directors" Permission Set, giving only directors the ability to override the discount limit.
Why Custom Permissions are feature flags built into the platform
A Custom Permission is a named flag - a label like "Can Approve Discount Over 20%" or "Beta Feature Access" - that you assign to users through Permission Sets and check from Apex, Flow, or validation rules. It doesn't grant access to any object or field on its own; it only grants the right to execute a code path that knows to look for it. That separation makes Custom Permissions the cleanest way to gate behaviour without distorting the security model.
The reason this matters is that without Custom Permissions, admins reach for proxy attributes - a Profile, a Role, a checkbox on the User record - and over time those attributes accumulate meanings nobody documented. A Custom Permission is named for what it does, can be assigned from a Permission Set the same way as any other entitlement, and is straightforward to audit later because the name carries the intent. Reach for it whenever you need to ask "is this user allowed to do this specific thing" anywhere in your code or configuration.
How to set up Custom Permissions
Custom Permissions are admin-defined permission flags that you can grant via Profiles or Permission Sets and check in Apex / Validation Rules / Flow / Visualforce. They let you build feature gates without inventing custom "is enabled" checkbox fields per user.
- Open Setup → Custom Permissions
Setup gear → Quick Find: Custom Permissions → Custom Permissions.
- Click New
Top-right.
- Set Label, Name, Description
Label is the admin-facing name; Name is the API used in code.
- Tick Protected Component if applicable
Same as Custom Labels — ISV protection toggle.
- Save
Permission is created. By itself it does nothing — it has to be granted.
- Open a Profile or Permission Set → Custom Permissions section → Add
Grant the permission to the right population.
- Reference from code or admin tools
Apex: FeatureManagement.checkPermission('MyPermission'). Validation Rule: $Permission.MyPermission. Flow: $Permission.MyPermission. Visualforce: $Permission.MyPermission.
Custom Permissions can require other Custom Permissions — a dependency tree. Useful for tiered features ("Advanced" requires "Basic").
Either path works; modern best practice is Permission Set.
Apex (FeatureManagement.checkPermission), Validation Rules ($Permission.X), Flow ($Permission.X), Visualforce ($Permission.X).
- Custom Permissions are a flag, not a value. They're true or false per user — no parameters. For configurable values per user, use Custom Settings instead.
- Granting a Custom Permission via Profile is the same as via Permission Set — but modern best practice is to use Permission Sets so granting is composable.
- Permission Sets that include Custom Permissions but reference renamed permissions break at runtime. The renamed permission resolves to null — check the Permission Set after a rename to confirm references.
How organizations use Custom Permissions
Custom Permission gates discount approval thresholds; business logic checked declaratively across Apex and Flow.
Beta-feature Custom Permissions enable early-access for select users; rollouts are controlled.
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…