Introduction

Origin

Salesforce’s journey with HTTP callouts began with the introduction of Remote Site Settings. Administrators had to allowlist specific external endpoints with this feature. This was done before Apex code could make callouts to them. It enforced a layer of explicit security. However, as integration needs grew more sophisticated, integration management became challenging. The rise of OAuth’s multi-step browser-based authentication flows contributed to this complexity. Managing callouts directly in Apex became cumbersome and error-prone.

To address these challenges, Salesforce introduced Named Credentials—a unified solution that combines endpoint definition with built-in authentication protocol support. Over time, this concept evolved further. It resulted in the introduction of External Credentials to separate endpoint and authentication concerns. This change improved security and reusability.

Introduction

Named Credentials in Salesforce offer a declarative method to define external system endpoints and their associated authentication parameters. By offloading authentication handling from Apex or Flow logic, Named Credentials simplify integrations and improve security.

Initially, Named Credentials bundled endpoint definitions and authentication details in a single “legacy” configuration. Salesforce has since modernized this approach by separating these concerns. The introduction of External Credentials enables reuse of authentication configurations across multiple endpoints. It also enforces explicit access control using Principals. This ensures that only authorized users or packages can perform outbound callouts.

In this article, you’ll explore:

• The purpose and benefits of Named Credentials.
• Differences between legacy and new types of Named Credentials.
• Step-by-step guides to creating both configurations.
• An overview of External Credentials and Principals, their purpose, and their role in modern callouts.

What Are Named Credentials?

A Named Credential is a powerful declarative tool in Salesforce that simplifies the configuration and management of external API callouts. It encapsulates the endpoint URL and authentication mechanism. This enables Apex and Flows to perform callouts without worrying about managing authentication. They also do not need to be concerned about remote site settings.

Once configured, Apex code and Flows can reference the Named Credential by name (using the callout: prefix). Salesforce handles the authentication handshake, token storage, and endpoint allowlisting automatically. This approach simplifies security audits, keeps credentials out of code, and streamlines maintenance when endpoints or credentials change. For more details refer SFDC Documentation.

Key Features and Benefits of Named Credentials

1. Simplified Authentication Handling:
   Salesforce automatically manages the authentication handshake for Apex callouts using a Named Credential. Developers don’t need to include authentication logic in their code, significantly reducing complexity and potential security risks.
2. No Remote Site Settings Required:
   When using a Named Credential, you don’t need to configure remote site settings separately for the specified endpoint. Salesforce implicitly handles this, streamlining setup.
3. Maintenance Flexibility:
   Named Credentials separate the endpoint URL and authentication details from the code. For instance:
   • If the endpoint URL changes, you only need to update the Named Credential.
   • All callouts referencing the Named Credential continue to work without any code changes.
4. Environment-Specific URLs:
   You can create Named Credentials with the same name but different endpoint URLs in separate Salesforce orgs. This is particularly useful when deploying across environments (e.g., dev, QA, production):
   • A single Apex class can reference the shared Named Credential name without hardcoding environment-specific URLs.
5. Private Connection Routing:
   Named Credentials include the OutboundNetworkConnection field, which routes callouts through private connections, enhancing network security.
6. URL Query Parameters:
   Named Credential URLs support appended paths and query parameters:
   • Example: callout:My_Named_Credential/some_path?format=json

Best Practices

1. Reuse Named Credentials: To minimize duplication, create reusable configurations. These configurations apply across multiple endpoints when using the new Named Credentials structure (Secured Endpoints and External Credentials).
2. Use Principals: Leverage External Principals for fine-grained access control and secure token storage.
3. Environment-Specific Deployment: Maintain consistency in Named Credential names across environments for seamless deployment.

Legacy vs. New Named Credentials

Legacy Named Credentials

A Legacy Named Credential stores both the endpoint URL and authentication details together on a single setup object.

To create one, navigate to Setup → Named Credentials. Select New Legacy from the dropdown next to the New button.Supported authentication protocols include OAuth 2.0, JWT, AWS Signature, and Basic Auth (username/password). Basic Auth is only available in the legacy mode.For more details refer SFDC Documentation.

Note – Legacy named credentials are deprecated and going to be unsupported in future releases.

New (Secured Endpoint) Named Credentials

In the revamped model, the Named Credential object solely defines the endpoint. This endpoint is now often termed a “Secured Endpoint.” Authentication settings live in a separate External Credential.

This design lets you link multiple Named Credentials to a single External Credential, so one OAuth or API key configuration can serve many services e.g., Google Drive and Google Calendar. Additionally, newer Named Credentials require users (and managed packages) to have explicit permission to invoke them, improving security governance LinkedIn.

Key Differences at a Glance

• Configuration Scope: Legacy bundles URL and auth; new splits them into Named vs. External Credentials.
• Reusability: Legacy auth is tied to one endpoint; new auth (External Credential) can serve many endpoints.
• Permission Model: Legacy is implicit; new requires explicit Principal permissions and User External Credential access.
• Metadata vs. Data: Metadata vs. Data: Legacy stores tokens in metadata. They are in plain text on export. New named credentials stores tokens in a secure data object (UserExternalCredential). This avoids exporting secrets.

How to Create a Legacy Named Credential

1. In Setup, enter Named Credentials in the Quick Find box, then select Named Credentials.
2. Click the dropdown next to New and choose New Legacy.
3. Fill in the Label, Name, URL, and choose the Identity Type (Per User or Named Principal).
4. Select the Authentication Protocol (e.g., OAuth 2.0 or Password Authentication) and enter credentials.
5. Save, and assign access via profiles or permission sets if you chose Per User authentication .
6. For more details steps refer SFDC Documentation.

Understanding External Credentials and Principals

An External Credential encapsulates the authentication configuration (OAuth flow, API keys, JWT details) separately from any endpoint.Within it, Principals define which Salesforce users or permission sets are authorized to use those credentials when making callouts.

The actual runtime tokens are stored in the UserExternalCredential object. This ensures the secrets remain in a secure data store. They are not stored in metadata exports Medium. This explicit permissioning model enhances security. It requires both the Named Credential and the External Credential Principal to be granted before a callout succeeds LinkedIn.

With this knowledge, you can confidently choose between legacy and modern Named Credentials. You can leverage External Credentials for reusable authentication. This setup allows for robust, secure integrations with external systems in Salesforce.

How to Create a New Named Credential with External Credential

1. In Setup, search for External Credentials and click New External Credential.
2. Enter its Label, Name, and choose the Authentication Protocol (OAuth, JWT, AWS Signature, Custom, etc.).
3. Under the External Credential, create one or more Principals. Define which Permission Sets or Profiles can use it. Specify secret parameters, such as client ID/secret or API key.
4. Navigate to Named Credentials, click New, set Type to Secured Endpoint, and select your External Credential via lookup.
5. Specify the URL, additional header settings if needed, and save. Assign users to the External Credential’s Principals to grant callout permissions.
6. For more details steps refer SFDC Documentation.

Example

Let’s see what the Apex code looks like without a named credential. Notice that the code becomes more complex to handle authentication, even if we stick with basic password authentication. Coding OAuth is even more complex and is an ideal use case for named credentials.

HttpRequest req = new HttpRequest();
req.setEndpoint('https://my_endpoint.example.com/some_path');
req.setMethod('GET');

// Because we didn't set the endpoint as a named credential, 
// our code has to specify:
// - The required username and password to access the endpoint
// - The header and header information
 
String username = 'myname';
String password = 'mypwd';
  
Blob headerValue = Blob.valueOf(username + ':' + password);
String authorizationHeader = 'BASIC ' +
EncodingUtil.base64Encode(headerValue);
req.setHeader('Authorization', authorizationHeader);
   
// Create a new http object to send the request object
// A response object is generated as a result of the request  
  
Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody());

Let’s see the updated apex code, by using a named credential and an appended path specify the callout’s endpoint.

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:My_Named_Credential/some_path');
req.setMethod('GET');
Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody());

The referenced named credential specifies the endpoint URL and an external credential that specifies authentication settings.

References –

• Named Cred