Named Credentials and External Credentials in Salesforce

Introduction

Salesforce strongly recommends the improved named credential model that arrived in Winter '23 instead of legacy named credentials. In the preferred model, a Named Credential defines the endpoint and transport behavior, while an External Credential defines how Salesforce authenticates and which principals users are allowed to use.

That is the big mental shift. A named credential is no longer the whole integration setup. Salesforce intentionally split the problem into endpoint definition, authentication rules, authorization mapping, and encrypted token storage so admins and developers can manage each concern in the right place.

What changed from legacy named credentials

Legacy named credentials bundled endpoint and auth more tightly together. The newer model is more modular and more secure. Salesforce's docs emphasize reuse and explicit authorization, while Nebula's article does a good job translating those improvements into day-to-day delivery benefits: less custom Apex for headers and secrets, cleaner permission-set based access, and a better security story for real orgs.

Using a named credential also keeps the callout URL out of Apex. Salesforce's getting-started guidance is clear that if you skip named credentials and specify a raw URL instead, you are back to handling auth details yourself.

Credential model

Salesforce documents the current design as a schema of related objects. That matters because the architecture is deliberately composable: one external credential can serve multiple named credentials that share the same authentication boundary.

A useful rule of thumb is this: if several endpoints belong to the same external platform and should authenticate the same way, keep one external credential and create multiple named credentials. If the authentication boundary changes, create a different external credential.

Named principal vs per-user

• Named principal: usually the right default for backend integrations where business logic runs on behalf of the org, not the individual human user.
• Per-user: the right choice when the external system should see the caller's own identity. Salesforce's OAuth callout guide notes that per-user callouts automatically incorporate the current user's context and pass that user's token.
• Access control: creating the credential does not grant everyone the right to use it. Principals are mapped to permission sets, profiles, or permission set groups.

Headers, packaging, and operational details

The docs and Nebula article line up on an important practical point: the newer model is not only about OAuth browser flow. It is also much better for integrations that need API keys, signature inputs, or custom header values without pushing those concerns down into Apex.

• Custom headers: place endpoint-specific headers on the named credential, or shared headers on the external credential. Salesforce also provides formula functions for header values when you need derived content.
• Supported patterns: the official docs cover OAuth 2.0 variants, AWS Signature v4 and AWS STS variants, basic auth, JWT, and custom authentication scenarios.
• Packaging reality: certificates, tokens, and other sensitive principal values are not packageable. After install or deployment, populate them in the target org through the UI or the Connect REST API.
• Managed package access: if packaged Apex references a named credential that is not installed in the same managed package, the subscriber must add the package namespace to that named credential's allowed namespaces.
• Current package behavior: Salesforce's packaging guide states that starting in February 2026, named credentials added to a managed package default to developer control. Use subscriber control only when customers truly need to edit the URL or auth settings after install.
• Automation options: Salesforce exposes Connect API, Connect REST API, and Apex references for creating and managing named credentials and external credentials programmatically.

Example

Your code should reference the logical credential name instead of a raw URL. That keeps endpoint resolution, authentication, and secret handling in setup where they belong.

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:GitHub_Gists/gists');
req.setMethod('GET');
req.setHeader('Accept', 'application/json');

Http http = new Http();
HttpResponse res = http.send(req);

Apex does not need to know whether the credential is using a named principal or a per-user token. The named credential resolves the endpoint, and the linked external credential provides the authentication behavior.

This pattern also travels well across environments. Salesforce's packaging guidance explicitly notes that different orgs can use named credentials with the same logical name and different physical URLs, allowing the same Apex code to move through sandbox and production without endpoint branching. After deployment, validate the credential in a sandbox or testing org before production use.

Common mistakes

• Creating a named credential and forgetting that principal access still has to be granted through a permission set, profile, or permission set group.
• Choosing per-user authentication for a pure system integration that really wants one shared service account.
• Leaving API keys, signature inputs, or bearer-token logic in Apex when the same concern belongs in external credential parameters or custom headers.
• Assuming metadata deployment moved secret values, certificates, or OAuth tokens with it.
• Trying to inspect User External Credential records through SOQL, Apex, or standard APIs even though Salesforce does not expose those records that way.
• For package authors, forgetting allowed namespaces or the February 2026 developer-control default for managed-package named credentials.

Recommendation

For new outbound integrations, use Salesforce's preferred named credential schema by default. Model one external credential per authentication boundary, then create as many named credentials as you need for the individual endpoints behind that boundary.

Choose named principal when Salesforce should act as one integration identity. Choose per-user when the external system must evaluate each person's own token, scopes, or audit trail. Keep headers and secrets declarative, keep code pointed at callout:Name, and make post-deploy credential population part of the delivery checklist rather than an afterthought.

References

• Get Started with Named Credentials
• Named Credentials Glossary
• Use the Named Credential in a Callout
• Enable User External Credentials
• Package Named Credentials
• Populate External Credential Principals
• Named Credential Formula Functions
• Named Credential API Links
• Learn What External Credentials Mean for You and Your Salesforce Org