Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesiTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Salesforce Named Credentials give an API callout a reusable endpoint and authentication setup, so Apex does not need to hard-code connection details or secrets. The current design pairs a Named Credential—the endpoint and transport—with an External Credential—the authentication protocol and principals that define who can authenticate. Salesforce introduced this extensible architecture in Winter ’23 and recommends it over legacy Named Credentials, which are deprecated and scheduled to be discontinued in a future release; Salesforce has not stated a discontinuation date.
What Named Credentials do in a Salesforce integration
A Named Credential gives Salesforce callout code a stable reference to a remote endpoint. It specifies the callout URL and transport settings, while its linked External Credential defines how Salesforce authenticates and authorizes to that service. Salesforce describes the Named Credential as specifying the endpoint URL and required authentication parameters in one definition, while the current architecture separates those responsibilities for reuse and administration.
In Apex, a callout can refer to the Named Credential instead of embedding the remote URL and authentication details in the code. The same credential model can also be used with External Data Sources and External Services. External Credentials support authentication protocols including OAuth and AWS Signature Version 4; Salesforce also documents custom headers for additional use cases.
How the pieces fit together
- Named Credential: Identifies the endpoint and transport for the callout.
- External Credential: Defines the authentication protocol and one or more principals.
- Principal: Represents the identity Salesforce uses at the remote system, either a shared integration identity or an individual user.
- Permission assignment: Associates a principal with permission sets, profiles, or permission set groups so eligible Salesforce users can use it.
- User External Credential: Stores encrypted user tokens. Salesforce says these records are not exposed through SOQL, Apex, or APIs.
Choose the identity the remote service should see
The central design decision is whether an API request should represent one shared integration account or the Salesforce user who initiated it. Neither approach is inherently more secure: choose according to the remote system’s authorization model and the access users need.
#1 Best Overall
| Decision point | Named principal | Per-user principal |
|---|---|---|
| Identity seen by remote service | A shared integration identity | The current Salesforce user’s identity |
| Permissions | Common authorization configured for the integration account | User-specific authorization at the remote service |
| Authentication | Uses the shared credential configuration | Each user must authenticate; Salesforce includes the current user context and access token in the callout |
| Access administration | Control which Salesforce users can access the principal through permission assignments; manage the shared identity at the remote service | Grant Salesforce users access to the principal and manage their individual remote authentication and authorization |
A named principal fits background jobs and integrations where the remote service should see a service account with shared permissions. Per-user authentication fits cases where the remote service must evaluate the actual user’s permissions or maintain user-level accountability. For the per-user model, a callout will not work for a user until that user completes authentication.
Set up an OAuth Named Credential
Salesforce’s documented OAuth flow connects the authentication definition to the endpoint, grants access, and then uses the credential in the callout. An external auth identity provider can be part of the flow where required.
- Configure an external auth identity provider if needed. Include it when the OAuth browser flow or selected identity-provider arrangement requires one.
- Create an External Credential. Select the authentication protocol, such as OAuth, and configure its principal as named or per-user.
- Create a Named Credential. Set the service endpoint and link the credential to the External Credential.
- Grant principal access. Assign the appropriate permission set, profile, or permission set group to users who should be allowed to use the principal.
- Complete authentication. Configure the shared identity or have each per-user participant authenticate. A newly created credential may show a “Not Configured” status until its authentication setup is complete.
- Use the Named Credential in the callout. Reference it from Apex or the supported Salesforce feature that needs the endpoint.
Keep endpoint configuration and authentication ownership clear: administrators should know who can alter the destination, who can use each principal, and how credentials are refreshed or revoked in the remote service.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Migrate from legacy Named Credentials
Salesforce recommends the improved, extensible Named Credentials architecture introduced in Winter ’23. Legacy Named Credentials are deprecated and will be discontinued in a future release, but Salesforce’s documentation does not provide a date. Treat migration as an architecture update rather than simply renaming an existing record: create an External Credential with the intended protocol and principal, associate it with the endpoint through a Named Credential, grant access, and complete authentication before switching callouts.
Inventory every integration that depends on a legacy credential, including Apex, External Data Sources, and External Services. Confirm whether each callout should use a shared identity or per-user identity, and verify the permission assignments and authentication process in the target org before retiring the old configuration.
Package and deploy credentials safely
For a managed second-generation package, include the Named Credential and External Credential, any external auth identity provider needed for the OAuth browser flow, and the permission set that grants access to the principal. Named Credentials are not automatically included in packages; explicitly include one when packaged Apex or an external data source refers to it. A subscriber may also supply a credential with the expected name, subject to package namespace allowance rules.
Rank #4
Certificates and tokens are not packageable. After installation, populate them in the target org through the Salesforce UI or Connect REST API, following the chosen authentication flow. A package can deliver metadata, but it cannot deliver a customer’s live secret or authenticate on that customer’s behalf.
Developer control or subscriber control?
Since February 2026, packaged Named Credentials default to developer control. This determines who controls the credential configuration after installation. Subscriber control can be appropriate when each customer uses a different service subdomain or connects through an on-premises gateway; developer control can suit a package whose endpoint configuration is intended to remain centrally controlled by its publisher. Decide based on who owns the destination and authentication settings in each deployed org.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Protect callouts when managed-package code changes credentials
Salesforce disables callouts if managed-package code programmatically updates a Named Credential. The safeguard prevents an authenticated connection from being silently redirected by a code-driven change. After reviewing the change and confirming the destination and authentication configuration, a subscriber administrator must re-enable callouts.
Include this behavior in deployment and incident procedures: a successful metadata or package update does not necessarily mean integrations can immediately resume. Have an administrator validate the credential change and restore callout operation through the applicable Salesforce controls.
Quick Recap
Salesforce implementation references
- Get Started with Named Credentials
- Named Credentials Glossary
- Create an OAuth Named Credential and Use the Named Credential in a Callout
- Package Named Credentials and Populate External Credential Principals
- Update or Delete an OAuth Named Credential
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
