by Paul Kissick 
Are you an admin or developer who’s recently created a Named Credential, and clicked New instead of New Legacy and felt a bit confused about the difference? Read on.
Back in Winter 2022, Salesforce introduced the latest version of Named Credentials, incorporating External Credentials. Named Credentials allow Salesforce to store integration credentials declaratively and use them in code or other data sources to make callouts from Salesforce to external services. External Credentials enhance this by making callouts from orgs more secure and extendable than the legacy version.
Learn more in Salesforce’s release notes
Key Features of External Credentials:
- Reuse credentials across different endpoints protected by the same authentication system.
- Grant users explicit access to make callouts using a specified set of credentials, by linking them to a permission set.
- Define arbitrary name/value pairs, such as API keys, passed along with the HTTP callout as headers.
- Customize user experiences with a new Connect API.
What Was Wrong with Legacy Named Credentials?
A few major issues stood out:
- They propagated to sandboxes, posing a significant security and data issue if sandbox users accessed production integrations.
- Anyone with knowledge could access them; there was no security attached to the credentials.
- API keys in headers required Apex code, adding complexity.
Salesforce set out to redesign Named Credentials to remove these pain points, making them more secure.
Remember the 3 S’s – Security, Security, Security
Named Credentials no longer store the credentials themselves. Instead, a new External Credential record holds the authentication details, while the Named Credential retains the endpoint being accessed. This enables an org to reuse the same credentials across multiple endpoints for the same service, simplifying the security model.
Getting Started with External Credentials
The first step is to create a Principal for your External Credential. Principals store the user authentication credentials and delegate access to the credential via assignment on either a Profile or Permission Set, managed under the External Credential Principal Access section.
For namespaced packages, be sure to add the namespace to the Named Credential. The example below is our own nebc namespace.
Finally, grant Read/Edit access to the User External Credential object, which holds the credentials. Without this access, regular users won’t be able to use the credentials. In the Winter ’25 release, Salesforce granted this access to standard profiles, but custom profiles will still need to be updated.
With the recent Winter 25 release, salesforce gave standard profiles access to this object, but custom profiles will need to be updated.
See the Winter ’25 release notes here.
Plenty of Protocols
External Credentials nearly match Legacy Named Credentials in terms of supported authentication protocols, with the exception of JWT (JSON Web Token) Token Exchange. However, they include the added benefit of Custom Authentication options.
Some integrations require specific API keys in callout headers or need to be signed with a preshared key. Traditionally, Apex code handled these cases, but with External Credentials, these requirements can now be managed declaratively.
For example, a Principal for a Custom Authentication External Credential can include a custom parameter, such as ClientID. Salesforce treats these as passwords, so the value is hidden on input.
This parameter can then be referenced in the Custom Header formula to protect it from unauthorised access. The example below demonstrates a callout header with “Authorization: Client-ID abc123.”
If you need a specific header value, add it either to the Named Credential (for a specific endpoint) or External Credential (for all callouts). Custom Headers are available for any Authentication Protocol, but with Custom Authentication, you have even more options to use custom properties in headers.
Code, Please
A final major benefit of External Credentials is the ability to create them using Apex. Salesforce has added new methods to the ConnectApi namespace, allowing packages (and local code) to create, edit, and delete External Credentials, Named Credentials, and, as of Winter ’25, Authentication Providers. This simplifies onboarding for AppExchange packages and increases security since Named and External Credentials created by packages are accessible only by those packages; any attempted access from other code will receive an error.
Explore the ConnectApi methods in Salesforce documentation.
Enhance Your Integrations Today with External Credentials
With External Credentials, Salesforce has reimagined security and flexibility for your org’s integrations, allowing you to safely store, reuse, and customise access to external systems with ease.
Find out more about External Credentials from Salesforce
Need help migrating your integrations to External Credentials, get in touch.