Why do profiles and user permissions have different names in Gearset than in Salesforce Setup?

Salesforce stores two names for each profile and each user permission. The following table shows what each name is for, using the System Administrator profile as the example.

Gearset reads and writes metadata through the Salesforce Metadata API, so Gearset labels items in comparison results with the API name rather than the Setup name. This matches how Gearset labels every other metadata item, covered in Why can't I find specific metadata in my Gearset comparison results?
​

A profile's API name also names its file. Salesforce returns one file per profile, with the .profile suffix, in the profiles folder of the retrieved package. The System Administrator profile therefore reaches your repository as Admin.profile.
​

Custom profiles created in Salesforce Setup normally use the same string for both names. A small set of standard Salesforce profiles is the exception, because Salesforce shipped them with shorter, older API names.

The following table lists the standard Salesforce profiles whose API name differs from the name shown in Salesforce Setup.

Three more standard profiles drop the spaces from their Setup name, giving ContractManager, SolutionManager, and ReadOnly. Other standard profiles keep their spaces, including Minimum Access - Salesforce and the Experience Cloud profiles.

Which standard profiles exist at all depends on the org's edition and on when the org was created. Salesforce converted Read Only to a custom profile in existing orgs at Summer '21, and orgs created in Spring '21 or later don't include it. For the current list, see Standard Profiles in Salesforce Help.
​

Query the Salesforce Tooling API in the org you're comparing. This needs access to Developer Console in that org.

Salesforce returns FullName only when a query matches exactly one profile. A query matching two or more profiles returns an error rather than results, so query one profile at a time.
​

Deploying the profile to source control from a Gearset comparison gives you the same answer: the file name in the profiles folder is the profile's API name.
​

A custom profile named Admin and the System Administrator standard profile both resolve to Admin in the Salesforce Metadata API. A deployment can then update the wrong profile.
​

Avoid giving a custom profile any of the standard profile API names listed earlier in this article, such as Admin, Standard, or ReadOnly.
​

User permissions appear in Gearset comparison results as Profile: User permission items, and Gearset labels them with their API name for the same reason it labels profiles that way. The gap between the two names is often wider for user permissions than for profiles.
​

The following table shows Salesforce user permissions whose API name differs sharply from the label shown in Salesforce Setup.

Take particular care with API Enabled, whose API name is ApiEnabled, and Api Only User, whose API name is ApiUserOnly. The words appear in a different order in each name, which makes these two permissions easy to mix up.
​

Look the user permission up in Salesforce's own reference, then adjust the name it gives you.

That page lists most user permissions, but not all of them. EditKnowledge, the API name for Manage Articles, is one example it leaves out. For a permission you can't find there, retrieve the profile from a Gearset comparison and read the <userPermissions> entries in the .profile file.
​

Use the API name, not the Salesforce Setup name, for these tasks:

Gearset deploys the profile the same way either way. The difference in names affects how you find and identify an item, not whether the deployment works.
​

What should I do if I get stuck with anything?

If you ever need support, just contact our live chat support by clicking the blue button in the bottom right in every Gearset screen.