name: apex-custom-permissions-check description: "Custom Permissions in Apex: FeatureManagement.checkPermission, $Permission global variable, permission-set gating of feature code, Custom Permission metadata. NOT for CRUD/FLS enforcement (use security-apex-crud-fls). NOT for standard Salesforce permissions (use permission-set-architecture)." category: apex salesforce-version: "Spring '25+" well-architected-pillars:

• Security
• Operational Excellence tags:
• apex
• custom-permissions
• featuremanagement
• permission-sets
• authorization triggers:
• "featuremanagement.checkpermission apex custom permission"
• "gate apex feature behind custom permission"
• "custom permission vs profile permission best practice"
• "how to check custom permission in lwc and apex"
• "custom permission in validation rule and formula"
• "feature flag pattern salesforce custom permission" inputs:
• Feature or code path to gate
• Target user populations (profiles / permission sets)
• Test scenarios needing permission toggling outputs:
• Custom Permission metadata
• Apex check pattern
• Permission Set assignment plan
• Test class using System.runAs with permission set dependencies: [] version: 1.0.0 author: Pranav Nagrecha updated: 2026-04-21

Apex Custom Permissions Check

Activate when gating code paths, feature availability, or field-level behavior behind a Custom Permission. Custom Permissions are the platform's feature-flag primitive — declarative on/off tokens assigned via Permission Sets or Profiles that Apex, LWC, formulas, and validation rules can check consistently.

Before Starting

• Create the Custom Permission metadata first. Setup → Custom Permissions or via -meta.xml deployment.
• Assign via Permission Set, not Profile for maintainability.
• Use FeatureManagement.checkPermission for runtime checks — not the deprecated Schema describe path.

Core Concepts

Custom Permission metadata

<CustomPermission xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>Approve Big Deals</label>
    <isLicensed>false</isLicensed>
</CustomPermission>

API Name is the handle used in Apex / formulas.

Apex check

Boolean canApprove = FeatureManagement.checkPermission('Approve_Big_Deals');
if (!canApprove) throw new AuraHandledException('Not authorized');

Per-user, transaction-cached. Safe to call repeatedly.

Formula / validation rule

$Permission.Approve_Big_Deals returns Boolean for declarative gating.

LWC

import hasApprove from '@salesforce/customPermission/Approve_Big_Deals';

Returns Boolean at module load — evaluate in getters.

Testing

@IsTest
static void canApprove() {
    User u = TestUserFactory.makeUser();
    insert new PermissionSetAssignment(
        AssigneeId = u.Id,
        PermissionSetId = [SELECT Id FROM PermissionSet WHERE Name = 'Big_Deal_Approvers'].Id
    );
    System.runAs(u) { ... }
}

Common Patterns

Pattern: Gate Apex service entry point

public with sharing class ApprovalService {
    public void approve(Id oppId) {
        if (!FeatureManagement.checkPermission('Approve_Big_Deals')) {
            throw new AuraHandledException('Not authorized');
        }
    }
}

Pattern: LWC conditional render

import hasApprove from '@salesforce/customPermission/Approve_Big_Deals';
export default class Approve extends LightningElement {
    get showButton() { return hasApprove; }
}

Pattern: Validation rule gate

AND(ISCHANGED(Status), Status='Approved', NOT($Permission.Approve_Big_Deals))

Decision Guidance

Recommended Workflow

1. Define the feature boundary — what code runs for privileged users only.
2. Create the Custom Permission metadata.
3. Create a Permission Set granting it; assign to users.
4. Add FeatureManagement.checkPermission at service entry points.
5. Mirror the check in LWC and formulas where needed.
6. Write Apex tests using System.runAs + PermissionSetAssignment.
7. Document the permission in the feature runbook.

Review Checklist

• Custom Permission metadata exists with clear label
• Assigned via Permission Set (not Profile)
• Apex uses FeatureManagement.checkPermission
• LWC uses @salesforce/customPermission/ import
• Formulas use $Permission.<API_Name>
• Tests cover both granted and denied
• No hardcoded user Ids in permission checks
• Permission documented in feature doc

Salesforce-Specific Gotchas

1. isLicensed=true requires the user's managed-package license; non-licensed users cannot receive it even if assigned.
2. Schema.describe for Custom Permissions is deprecated — use FeatureManagement.checkPermission.
3. Custom Permission grants propagate through Permission Set Groups — audit muting flags on groups.

Output Artifacts

Related Skills

• security/permission-set-architecture — permission-set design
• security/security-apex-crud-fls — CRUD/FLS enforcement
• lwc/lwc-user-permission-aware-components — LWC permission checks