CustomPermission

Represents a permission that grants access to a custom feature. This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

CustomPermission components have the suffix .customPermission and are stored in the customPermissions folder.

Version

CustomPermission components are available in API version 31.0 and later.

Special Access Rules

As of Summer ’20 and later, only users who have one of these permissions can access this object:

View Setup and Configuration
Manage Session Permission Set Activations
Assign Permission Sets

Fields

Field Name	Field Type	Description
connectedApp	string	The name of the connected app that’s associated with this permission. Limit: 80 characters.
description	string	The custom permission description. Limit: 255 characters.
isLicensed	boolean	Required. Read-only. Indicates whether the appropriate Salesforce license is required before accessing the permission (`true`) or not (`false`).
label	string	Required. The custom permission label. Limit: 80 characters.
requiredPermission	CustomPermissionDependencyRequired[]	Indicates which custom permissions are required by the parent custom permission. This field is available in API version 32.0 and later.

CustomPermissionDependencyRequired

CustomPermissionDependencyRequired determines whether a custom permission is required by the parent custom permission. A required custom permission must be enabled when its parent is enabled.

Field Name	Field Type	Description
customPermission	string	Required. The custom permission name.
dependency	boolean	Required. Indicates whether this custom permission is required by the parent custom permission (`true`) or not (`false`).

Declarative Metadata Sample Definition

The following is an example of a CustomPermission component.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomPermission xmlns="http://soap.sforce.com/2006/04/metadata">
3   <connectedApp>Acme</connectedApp>
4   <description>Read and edit access for Acme accounts.</description>
5   <label>Acme Account Full Access</label>
6   <requiredPermission>
7      <customPermission>Acme_Account_Read</customPermission>
8      <dependency>true</dependency>
9   </requiredPermission>
10</CustomPermission>

The following is an example package.xml that references the previous definition, as well as other custom permissions that are associated with a connected app.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3   <types>
4      <members>Acme</members>
5      <name>ConnectedApp</name>
6   </types>
7   <types>
8      <members>Acme_Account_Email_Read</members>
9      <members>Acme_Account_Phone_Edit</members>
10      <members>Acme_Account_Full_Access</members>
11      <members>Acme_Account_Read</members>
12      <name>CustomPermission</name>
13   </types>
14   <types>
15      <members>Acme_Account_Email_Read</members>
16      <members>Acme_Account_Phone_Edit</members>
17      <members>Acme_Account_Full_Access</members>
18      <members>Acme_Account_Read</members>
19      <name>PermissionSet</name>
20   </types>
21   <version>64.0</version>
22</Package>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.

Metadata API Developer Guide