Explained: Connected App and Named Credentials in Salesforce

Integrating Salesforce with other systems has always been one of the trickiest parts of CRM customization. Whether you’re connecting to an external API, a third-party service, or even another Salesforce org, handling authentication, tokens, and credentials can quickly become complicated. That’s where Connected Apps and Named Credentials come in, these powerful tools that make Salesforce integrations secure, scalable, and much easier to manage.

Think of these features as the middlemen that handle all the technical handshake details between Salesforce and external systems. Instead of hardcoding passwords or storing tokens in your code, sfdc connected app and named credentials salesforce provide a clean, secure, and admin-friendly way to connect systems safely.

In this guide, we’ll walk through everything you need to know about Connected App and Named Credentials, from fundamental concepts to practical use cases that will help you to use them effectively in projects.

Before you start, don’t miss our blog: What Is Integration? 5 Big Benefits of Salesforce Integration, it’s the perfect place to begin!

Why Salesforce Introduced Connected Apps and Named Credentials

Before Salesforce provide Connected Apps and Named Credentials features, integrations were often risky and hard to maintain.

Developers stored API keys, usernames, and passwords directly in Apex code or Custom Settings, which were not always encrypted. When tokens expired or credentials changed, someone had to hunt through code to update them manually.

This old method created three big problems : security risks, maintenance headaches, and lack of visibility.

Security Risks

First, there were serious security risk. Passwords and API keys sitting in code are a hacker’s dream. If someone got access to your codebase, they got access to everything.

Maintenance Headaches

Second, maintenance became a constant headache. When credentials changed (and they do), developers had to hunt through code to update them everywhere. Miss one spot? Your integration breaks.

Lack of Visibility

Third, there was no central control over credentials. Admins couldn’t easily see what credentials were being used where, making it nearly impossible to audit or manage access properly.

When someone left the company or a service needed to be disabled, finding and updating all the places where credentials existed became a detective mission.

Salesforce introduced Connected Apps and Named Credentials to fix these issues once and for all. Now you can :

• Manage authentication in one central place, eliminating scattered credential management.
• Use modern authentication protocols like OAuth 2.0, SAML, or JWT, which are far more secure than basic username and password approaches. You
• Eliminate the need to manually handle credentials in code, letting Salesforce handle the heavy lifting.
• Provide granular access control through admin-managed policies, giving you the oversight that was missing before.

What is a Connected App?

A Connected App is a configuration inside Salesforce that defines how external applications or systems can securely connect to your Salesforce data. Think of it as creating a special doorway that external applications can use to access your Salesforce information safely.

They act as a bridge which allowing external applications to access Salesforce data through standard authentication protocols like OAuth 2.0. When you create a Connected App, it defines several important things about how that connection works.

• How another application authenticates (whether that’s via OAuth, SAML, or OpenID Connect).
• It specifies what access the external application has through scopes and permissions
• And it determines who can use it by configuring profiles and permission sets.

Example

Here’s a practical example to make this concrete. You might create a Connected App so your external system can access Salesforce leads via OAuth 2.0. That external system gets a Consumer Key and Consumer Secret, which function like a username and password but are specifically designed for application-to-application communication. The external system uses these credentials to authenticate with Salesforce and get access tokens, which it then uses to make API calls and retrieve or update data.

The beauty of Connected Apps is that they give you control over exactly what external systems can do.

What is a Named Credential?

If a Connected App defines how external systems reach Salesforce, a Named Credential defines how Salesforce reaches external systems. It is one of the most important parts of sfdc connected app and named credentials salesforce integration architecture.

They’re a Salesforce feature that stores all the authentication details needed to call an external service. Instead of writing code that includes usernames, passwords, or API keys, you simply reference a Named Credential by name.

Salesforce handles all the authentication behind the scenes, managing tokens, refreshing sessions, and ensuring secure communication.

A Named Credential stores several key pieces of information. It stores :

• The external system’s URL, like an API endpoint that you want to call.
• The authentication method, which could be OAuth 2.0, JWT, password-based authentication, or reference to an external credential.
• Optionally, it can reference an Auth Provider that handles the authentication handshake for more complex protocols.

With Named Credentials, you don’t have to hardcode authentication details in Apex or Flows. Salesforce automatically handles token management, session refresh, and security.

Example

Here’s a simple example to illustrate how this works. If you want to call a third-party REST API from Apex, you can define a Named Credential with settings like this:

Name: My_Named_Credential  
URL: https://api.example.com  
Authentication: OAuth 2.0  
Auth Provider: My_Auth_Provider  

Then, your Apex code becomes beautifully simple. Instead of managing authentication manually, your code just refers to the Named Credential like this:

req.setEndpoint('callout:My_Named_Credential/api/data');

No passwords written in code, no tokens to manage manually, no worries about security vulnerabilities. Salesforce handles everything automatically based on your Named Credential configuration.

Understanding Named Credentials, External Credentials, principals, and Auth Provider

This is where Connected App and Named Credentials architecture gets more interesting, but don’t worry, we’ll break it down clearly.

Named Credentials: Legacy vs Enhanced

There are actually two types of Named Credentials in Salesforce, and understanding the difference is important for building modern integrations.

Legacy Named Credentials

Legacy Named Credentials bundle everything together in one package. The endpoint URL, authentication details, and settings all live in a single configuration. They’re simpler to set up but less flexible when your needs grow or change.

Enhanced Named Credentials

Enhanced Named Credentials introduces, more modular approach that separates concerns. This model uses four distinct components such as Auth Providers, External Credentials, Principals, and Named Credentials to make integrations more modular and flexible.

Four Key Components

To understand how Salesforce handles secure integrations, it helps to know the four main pieces that work together behind the scenes.

Auth Providers

Auth Providers take care of the authentication process. They handle the entire OAuth flow like requesting tokens, exchanging authorization codes, and refreshing tokens when they expire.

In simple terms, an Auth Provider knows how to log in to another system. Whenever Salesforce needs to connect to platforms like Google, Facebook, or another Salesforce org, the Auth Provider manages that whole sign-in and token exchange automatically.

External Credentials

External Credentials store the actual authentication details. They define what type of credential Salesforce should use, such as an API key, JWT token, OAuth credential, or password.

You can think of them as reusable authentication templates that you set them up once and use them across multiple integrations. This helps keep things consistent and avoids repeating the same configuration for every endpoint.

Principals

Principals answer the question: “Who is making this call?”

They define the identity Salesforce should use when connecting to an external service. This could represent one shared login for the entire org or unique logins for each individual user. Salesforce offers two main types of Principals: Named Principal and Per-User Principal.

Named Principal

This setup uses one shared identity for everyone in your Salesforce org. All users connect to the external system using the same credentials. It’s ideal for integrations where user-specific data isn’t required, for example, sending payment data or syncing records using a central service account.

Per-User Principal

This setup uses each user’s own credentials when connecting to the external system. Every user authenticates individually, and Salesforce stores their tokens securely. It’s perfect for user-level integrations such as connecting to a personal calendar or email system, where actions must be performed under each person’s identity.

Choosing the right Principal type is essential. If you want every user to access an external service as themselves, use Per-User. If you want all users to share one account, use Named Principal.

Named Credentials

Named Credentials tie everything together. They store the external system’s endpoint URL and link it with an External Credential, which uses a Principal to determine the user identity.

If OAuth is required, the Named Credential will also reference the Auth Provider to handle token management.

In short, Named Credentials connects all these pieces that defining where Salesforce connects and how it authenticates, all in one secure and simple configuration

How They Work Together

Here’s the relationship in practice. A Named Credential points to an External Credential. That External Credential uses a Principal to determine whose identity to use. And if the authentication method is OAuth, it relies on an Auth Provider to handle the token management.

So, when Salesforce connects to another system, the flow looks like this:

It uses the Named Credential, which references an External Credential, which authenticates using an Auth Provider, on behalf of a Principal.

This modular approach is powerful because it allows one External Credential to be reused across multiple Named Credentials. You can even map the same credential to different users or different endpoints without duplicating configuration.

Why Did Salesforce Split These Apart?

The enhanced model is more flexible than the legacy approach. You can reuse the same authentication setup across multiple endpoints, which reduces duplication and makes maintenance easier.

You can use the same endpoint with different authentication methods for different scenarios. It’s like having building blocks you can mix and match instead of one rigid structure that you have to recreate every time.

For new projects, Salesforce recommends using the enhanced model because it provides better scalability, easier maintenance, and more granular control over how authentication works.

Connected Apps and Named Credentials: Use Cases and Real-World Examples

Let’s explore how Connected App and Named Credentials work in practical scenarios.

1. Using Named Credentials in Apex: Cross-Org Integration

Scenario

One common scenario involves syncing data between two Salesforce orgs. When an Account is created in Org A, Salesforce automatically sends that Account data through a custom REST API callout to Org B.

For complete step-by-step setup, see the related guide:“Uses of Salesforce REST API Endpoints: A Real-World Example with Connected Apps & Named Credentials.”

2. Using Named Credentials in Flow: Cross-Org Integration through External Services

Scenario

A common use case is to prevent duplicate Accounts between two Salesforce orgs.
When a user creates an Account in Org A (Sales), Salesforce automatically makes a REST API callout to Org B (Support) using an External Service in Flow and a Named Credential to check if the Account already exists.

Explore every step of this setup in detail in the companion guide:
“Using Salesforce External Services in Flow : Connect APIs Without Writing Apex Code.”

Enhanced Capabilities with External Credentials & Auth Providers

Recent Salesforce releases have introduced External Credentials and Auth Providers, bringing a new level of flexibility, security, and simplicity to integrations.

These enhancements change how admins and developers manage authentication inside Salesforce, making integrations more configuration-driven and less code-dependent.

Now, admins can:

• Configure multiple authentication methods such as API keys, JWT tokens, OAuth credentials, or even custom schemes directly from one place.
• Map users to external identities using Principals, enabling secure per-user authentication without any custom Apex code.
• Multiple authentication mechanisms can coexist, making it easy to switch or test different security approaches whenever needed.

This allows developers to design integrations that are secure, reusable, and admin-friendly which reducing the need to hardcode any authentication logic.

Flexible Authentication Options

External Credentials allow you to configure several authentication types for the same service. For instance, if an API supports both OAuth and API Key authentication, you can set up both methods and toggle between them by simply changing the External Credential reference no code updates required.

This flexibility is especially valuable during migrations, testing, or performance evaluations.

Custom Headers and Parameters

Salesforce lets you add custom HTTP headers or parameters within your External or Named Credentials. This is useful for including version headers, tracking IDs, or routing information that some APIs require.

These headers are automatically sent with every callout, ensuring consistency and reducing the chance of developer error.

Certificate-Based Authentication

For APIs that demand higher security, Salesforce supports mutual SSL/TLS authentication through External Credentials. You can upload your client certificate in Certificate and Key Management, link it to your External Credential, and Salesforce will automatically use it during the SSL handshake.

This provides a strong, password-free method of authentication that’s extremely difficult to compromise.

AWS Signature Version 4 Support

Integrating Salesforce with Amazon Web Services (AWS) is simpler than ever. Salesforce natively supports AWS Signature Version 4, so once you add your AWS access key and secret to your External Credential, Salesforce automatically generates the required signatures. This makes connecting to AWS services like S3, Lambda, or API Gateway secure and effortless.

Automatic Token Management

When using OAuth, Auth Providers in Salesforce handle token refresh automatically. As tokens expire, Salesforce renews them behind the scenes, no manual steps required. This ensures your callouts remain stable and integrations keep working without interruption.

Best Practices for Using Named Credentials

Following best practices when implementing Connected App and Named Credentials ensures your integrations remain secure, maintainable, and performant.

Use OAuth 2.0 Whenever Possible

Prefer OAuth 2.0 over Basic Authentication. OAuth is safer because it uses short-lived tokens instead of passwords, supports easy token revocation, and reduces the risk of credential exposure.

Basic authentication sends credentials with every call, which is far less secure.

Avoid Hardcoding Credentials

Never hardcode endpoints, usernames, or tokens in Apex or Flows. Always reference a Named Credential instead.

This centralizes authentication, keeps sensitive data out of your codebase, and allows admins to update credentials without developer help.

Choose the Right Principal Type

Select the correct Principal based on how your integration should authenticate. Use user-specific principals when each user must connect under their own identity, and org-wide principals when all users can share the same service account.

Choosing the right type prevents access errors and maintains data security.

Request Minimal Scopes in Connected Apps

When creating a Connected App, only request the scopes you truly need. For example, use read-only access if your integration only reads data.

Limiting scopes follows the principle of least privilege and minimizes damage if a token is compromised.

Adopt Enhanced Named Credentials

For new projects, use Enhanced Named Credentials with External Credentials, Auth Providers, and Principals.

They offer better flexibility, reusability, and security while aligning with Salesforce’s future roadmap.

Control Access with Permission Sets

Restrict who can use specific Named Credentials with permission sets or profiles.

Apply stricter controls for sensitive systems like HR or payment gateways, and review access periodically.

Considerations When Using Named Credentials

Before implementing integrations using Connected App and Named Credentials, keep a few important Considerations in mind to ensure success.

Supports HTTPS Endpoints

For security reasons, Salesforce requires all external callouts to use HTTPS. Plain HTTP endpoints are not allowed.
If your external service only provides HTTP access, work with that service provider to enable HTTPS before integrating it with Salesforce.

Verify User Permissions

To create or modify Named Credentials or External Credentials, users need the proper permissions. The “Customize Application” permission is typically required for setup.
If you’re using Enhanced Named Credentials, you may also need separate permissions for Auth Providers and External Credentials.

Match Callback URLs Exactly in Connected Apps

When configuring a Connected App for OAuth authentication, the callback URL must match exactly between Salesforce and the external system. Even minor differences like missing slashes, wrong case, or protocol mismatches can cause authentication to fail.

Configure Required API Headers

Some external APIs require specific HTTP headers in addition to authentication details. These might include Content-Type, API Version, Authorization, or Tracking IDs.
You can configure these custom headers directly in your Named Credential settings, ensuring every callout includes the correct information automatically.

Troubleshooting Common Issues

Even with proper setup, issues can occur in Connected App and Named Credentials integrations. Here’s how to fix the most common ones:

Unauthorized Endpoint Error

If Salesforce blocks a callout, check Remote Site Settings. Legacy Named Credentials still rely on them, though enhanced models usually handle this automatically.

Authentication Failures

Confirm that credentials are correct, tokens haven’t expired, and your Auth Provider configuration matches the external service’s requirements. Check external system logs for detailed error codes.

External Credential Principal Access

If you see an error like this

EXCEPTION: We couldn’t access the credential(s). You might not have the required permissions, or the external credential “External Credential” might not exist.

This means the user doesn’t have the required External Credential Principal Access permission.
Without it, Salesforce can’t access the credentials needed for the integration.
To fix this, grant the user access through a Permission Set or Profile that includes this permission. Once assigned, the integration will work as expected.

Conclusion

Connected App and Named Credentials are the foundation of secure and scalable integrations. Together, they remove the need for hardcoded credentials, simplify authentication, and provide centralized control over access and security.

Connected Apps act as secure gateways that allow external systems to communicate with Salesforce through modern authentication protocols like OAuth 2.0.
Named Credentials, on the other hand, let Salesforce safely connect to external systems without ever exposing passwords or tokens in your code

The key to success is knowing when to use which tool. Use Connected Apps when external applications need to access Salesforce data. Use Named Credentials when Salesforce needs to call external APIs. For user-specific integrations, configure Per-User Principals so each user can connect with their own credentials.

Follow best practices and Enhanced Named Credentials, with External Credentials, Auth Providers, and Principals, take this to the next level that giving admins fine-grained control and developers more flexibility.

In short: Connected Apps open the door for others to reach Salesforce,
and Named Credentials open the door for Salesforce to reach others, both securely, efficiently, and confidently.

FAQs