A named credential defines where a callout goes. An external credential defines how it authenticates. Salesforce split them apart in Winter '23, and the split is the whole point: one external credential can serve several named credentials, so a system with four endpoints does not need four copies of the same credentials.
The practical payoff is that your Apex stops containing endpoints and secrets. You write callout:My_Service/orders, Salesforce resolves the host and attaches the authentication, and the credential itself never appears in code or in a deployment.
How the two objects divide the work
| Named credential | External credential | |
|---|---|---|
| Holds | The endpoint URL and callout options | Authentication protocol and principals |
| Referenced in Apex | Yes, as callout:Name | No, indirectly through the named credential |
| Reusable | One endpoint each | Shared by many named credentials |
| Contains secrets | No | Yes |
The reuse direction is worth being deliberate about. Several named credentials pointing at one external credential is the intended shape: production and sandbox endpoints of the same vendor, or several base paths on the same host, sharing one authenticated identity.
Two things you stop having to do
Remote site settings. Callouts to an external host normally require a remote site setting. For an endpoint defined in a named credential, you can skip it. Salesforce already knows the host is intentional because you configured it.
Authentication code. Salesforce manages authentication for Apex callouts that specify a named credential as the endpoint, so your code does not. No token refresh logic, no expiry handling, no secret in a custom setting that shows up in a deployment.
That second one is the quiet security win. The most common way credentials leak out of a Salesforce org is not an attack, it is a protected custom setting that somebody retrieved as metadata.
Choosing a principal type
The principal decides whose identity the callout runs as, and this is the decision that is hard to reverse later.
| Named Principal | Per User Principal | |
|---|---|---|
| Whose credentials | One set, configured by an admin, used for everyone | Each user's own |
| The external system sees | One service account | The individual user |
| Setup burden | One time | Each user authenticates once |
| Right for | Service integrations, syncs, backend jobs | Acting on behalf of a person |
Pick Named Principal for anything that runs on a schedule or represents your system talking to theirs. Pick Per User Principal when the external system needs to apply its own permissions per person, or when the audit trail on their side has to name a real user.
Getting this wrong is expensive in one direction specifically. Starting with Named Principal and later needing per-user identity means every user has to authenticate for the first time, and every historical action on the far side is attributed to the service account with no way to reconstruct who did what.
The authentication protocols
| Protocol | What it is | Notes |
|---|---|---|
| Basic | Static username and password | Simplest, and the one to avoid where an alternative exists |
| OAuth 2.0 | Standard authorization flows | The default for modern APIs |
| OAuth 2.0 with JWT Bearer Flow | Certificate-signed assertions, no interactive consent | Requires a signing certificate created in the subscriber org |
| AWS Signature | Signed callouts to AWS resources over HTTP | Identity type must be Named Principal |
| Custom | Your own scheme | Uses a permission set, a sequence number, and named authentication parameters |
Two details that catch people out. The JWT Bearer Flow requires a signing certificate created in the subscriber org, which matters if you are packaging: the certificate cannot travel with your app, so installation documentation has to cover creating it. And AWS authentication requires Named Principal, so per-user AWS access is not a configuration you can choose.
Legacy named credentials are a dead end
Salesforce introduced the extensible named credential in Winter '23 and recommends it over the legacy version, which is no longer updated or enhanced.
Legacy named credentials still work, so nothing breaks tomorrow. But every capability added since Winter '23 lands on the new model, so a legacy credential is a component that will never get better. If you are creating one today, create the new kind. If you have existing ones, migrate the ones you actively change and leave the stable ones alone until a real reason arrives.
Where they stop, and external client apps start
Named credentials handle Salesforce calling out. They do nothing for the other direction.
When an outside system calls into Salesforce, the authentication is an OAuth app on the Salesforce side, which now means an external client app. Connected app creation through the UI was turned off by default on new orgs in Winter '26, and re-enabling it has required Salesforce Support since Spring '26.
| Direction | What you configure |
|---|---|
| Salesforce calls an external API | Named credential plus external credential |
| An external system calls Salesforce | External client app, with its own client ID and secret |
| Both | Both, and they are unrelated pieces of configuration |
Teams building a two-way integration routinely set up one half and are surprised the other half does not work. They are separate mechanisms that happen to both involve OAuth. Our comparison of connected apps and external client apps covers the inbound side.
Frequently Asked Questions
What is the difference between a named credential and an external credential?
The named credential holds the endpoint URL and callout settings. The external credential holds the authentication protocol and the principals that authorize callouts. They were split apart in Winter '23 so that one external credential can be shared by multiple named credentials.
Do named credentials replace remote site settings?
For the endpoint defined in the named credential, yes. Remote site settings are otherwise required for Apex callouts to external hosts, and you can skip that step for a host configured through a named credential. Callouts to any other host still need one.
What is the difference between Named Principal and Per User Principal?
Named Principal uses one set of credentials configured by an admin for every user, so the external system sees a single service account. Per User Principal has each user authenticate with their own credentials, so the external system sees the individual. Choose Named Principal for backend integrations and Per User Principal when the far side needs per-person identity.
Should I still use legacy named credentials?
No, for anything new. Salesforce introduced the improved extensible named credential in Winter '23 and states that legacy named credentials are no longer updated or enhanced. Existing ones keep working, so migration can follow your normal change cycle rather than being an emergency.
Which authentication protocols do external credentials support?
Basic authentication, OAuth 2.0, OAuth 2.0 with the JWT Bearer Flow, AWS Signature, and a custom protocol you define. AWS requires the Named Principal identity type. The JWT Bearer Flow requires a signing certificate created in the subscriber org.
Can one external credential be used by multiple named credentials?
Yes, and that is the main reason for the split. Several endpoints on the same system, or production and sandbox hosts of one vendor, can share a single authenticated identity instead of duplicating credentials.
Do named credentials work for inbound API calls to Salesforce?
No. They only cover Salesforce making outbound callouts. Inbound calls authenticate against an OAuth app on the Salesforce side, which for new work is an external client app rather than a connected app.
Related Articles
- Connected app vs external client app compared
- What is an external client app in Salesforce
- OAuth authentication in Salesforce
- Salesforce integration patterns and best practices
Sources
- Salesforce Help, Named Credentials, Create Named Credentials and External Credentials, and Authentication Protocols for Named Credentials: principal types, protocol list, Winter '23 change and legacy guidance. 2/ Salesforce Developers, Apex Developer Guide, Named Credentials as Callout Endpoints: remote site settings exemption and Salesforce-managed authentication. 3/ Salesforce Developers, Named Credentials Packaging Guide, Populate External Credential Principals. 4/ Salesforce Help, External Client Apps. Verified 2 September 2026.
