Named and External Credentials

Module 1 of 6 in the chapter The Admin’s Integration Toolkit, chapter 4 of the Integration Architect course. Each module stands on its own. Previous chapter: APIs, Contracts and Data Across the Wire · Next: External Services From an OpenAPI Spec

The question this module answers: When Salesforce calls another system, where does it keep the address and the secret, and who is allowed to use them?

In chapter 2, a client needed three things to make a call: where the server is, how to prove who it is, and the protocol to speak. This chapter is how an admin gives Salesforce all three, without writing code. Here’s the line I start with:

Endpoint and authentication live in the named credential. Protocol lives inside the OpenAPI spec.

This module is the first half. The next one is the second.

A named credential is the gateway to leaving Salesforce. It seems simple. Then you open it up, and it has so much power.

The Gatekeeper Out

Think about what a callout really is. Something running inside Salesforce, a flow, a piece of code, is about to leave the platform, carrying your data, to a system on the other side. That shouldn’t happen uncontrolled. Somebody needs to stand at the gate.

Named and external credentials, together, are that gatekeeper. They answer three questions every time something leaves:

• Is it allowed to go there? Only to the addresses on the list. That’s an allow list, often called a whitelist: a list of the only places that are permitted. Anything not on the list is blocked.
• Who is leaving? Not just any process in the org. Only the users and processes you’ve allowed, through a permission set, or a profile.
• How does it get in on the other side? The keys to the external system. And there’s a myriad of ways in: an authorization server and a token, a username and password, an API key in a header, a certificate. On the other side, it might sign in as one integration identity, or as the actual running user. It might need headers with values filled in at the moment of the call.

That’s why this has grown into something powerful, and a bit complex. It represents someone leaving the Salesforce platform, and every one of those questions has to have an answer before they do.

Click to enlarge

The gatekeeper out: where, who, and how.

The Problem They Solve

Remember Knocking on the Door: to call a protected API, the client often makes two calls. First to the authorization server, to trade its credentials for a token. Then to the API, with the token.

Now imagine doing that yourself, in code. When I ask a class what goes wrong, the answers come quickly.

You call for the token, use it once, and throw it away. Then the user clicks again two minutes later, and you sign in again. And again. You’re signing in on every click. So you decide to keep the token. Where? Put it somewhere every user’s code can reach, and now another user can reach it too, and use it to get into the other system.

Then the token runs out. If it’s good for eight hours, then in the eighth hour your call fails with a session expired error, and your code has to catch that, go back to the authorization server, sign in again, and retry. That’s the client move from the client–server tango, and someone has to write it.

And where’s the secret, the client secret or the password? In the code, or in a record. Neither is a place for a secret.

The old way to let Salesforce call out was a remote site setting. It’s an allow list out, and only that: an address, open to the whole org. It had nothing to do with who was leaving, or usernames and passwords, or credentials, or authorization servers. Everything else, you write yourself.

Or you use a named credential, and Salesforce does all of this for you.

Click to enlarge

Holding the token yourself, or not.

Two Parts of a Whole

Here’s what confuses people at first: it’s not one thing, it’s two, and they go together.

• The named credential is where. It holds the address of the system you’re calling, and gives it a name. Your flow or your code doesn’t call a URL; it calls the name, like callout:Redrock_Status.
• The external credential is how. It holds the way you sign in to the other system, the protocol, and the secrets that go with it, stored encrypted.

In Salesforce’s words: “A named credential specifies a callout endpoint and an HTTP transport protocol,” and “An external credential’s authentication protocol and user credentials authenticate the caller” (Named Credentials: Get Started (opens in a new tab), Salesforce Developers, checked 2026-11-01). One external credential can serve more than one named credential: one way of signing in, several addresses behind it.

Then there’s who is leaving. The external credential has one or more principals: the identity Salesforce signs in as, on the other system. And each principal is given to users through a permission set. A remote site setting is open to everyone. A named credential works only for the people you allow.

So when Steve Trucking’s flow tells Redrock a delivery’s status changed, the flow calls the named credential by name. The named credential knows Redrock’s address. The external credential knows how to sign in: it trades the client ID and secret for a token at Redrock’s authorization server, keeps the token, and gets a new one when it runs out. Salesforce does the dance for you.

Click to enlarge

Where: the flow calls the named credential by name.

Click to enlarge

How and who: the external credential signs in, and a permission set decides who may use it.

Every Way Out, One Gate

A flow isn’t the only way out. Nowadays, an admin might have some Apex too, maybe written with an AI helper. It’s the same gate.

In Apex, a callout is a handful of lines: say where you’re going, say the verb, send it, and check the answer. Here’s Steve Trucking telling Redrock a delivery was made:

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:Redrock_Status/v1/shipments/D-1042/status');
req.setMethod('POST');
req.setHeader('Content-Type', 'application/json');
req.setBody('{"state": "DELIVERED"}');
HttpResponse res = new Http().send(req);

Look at what’s not there. There’s no Redrock address, only callout:Redrock_Status, the named credential’s name, followed by the path. And there’s no token, no password, no key. The named credential supplies the address, the external credential signs in, and the permission set decides whether this user’s code may leave at all. Salesforce “manages all authentication for Apex callouts that specify a named credential… so that your code doesn’t have to” (Named Credentials as Callout Endpoints (opens in a new tab), Apex Developer Guide, checked 2026-11-01).

The same is true of a flow’s HTTP callout (module 3), of External Services (module 2), and of external data sources (chapter 18). Clicks or code, everything that leaves goes through the same gate.

Click to enlarge

Every way out, one gate.

So if you, or an AI, write Apex that calls out, check one thing first: does it call callout: and a named credential, or does it have an address and a secret written into it? Chapter 9 goes deeper into callouts in code: limits, waiting, and what happens when they fail.

The Ways to Sign In to the External System

The external credential is where you choose how Salesforce signs in to the external system: not how people sign in to Salesforce, but how Salesforce proves who it is to the system on the other side. And there are more choices than you’d expect. It’s a Swiss Army knife. Salesforce lists them in Authentication Protocols for Named Credentials (opens in a new tab) (Salesforce Help, checked 2026-11-01):

• No Authentication, for an open endpoint, like the public test server in chapter 2.
• Basic, a username and password. Salesforce stores it, encrypted, and only the users you allow can use it. It works, but a password is the weakest choice: use it only when the other system offers nothing better.
• Custom, for systems with their own scheme. The usual one is an API key in a header: you put the key in the external credential, and Salesforce adds the header to every call.
• OAuth 2.0, in several variants. For one system calling another with no person involved, the usual one is client credentials: Salesforce trades a client ID and secret for a token. There’s also a browser flow, for when a person signs in to the other system and allows access, and flows that sign with a certificate instead of a secret.
• JWT, a signed token, for server-to-server calls.
• AWS Signature Version 4, for calling Amazon Web Services.

Salesforce describes what OAuth gives it in a nice way: the other system hands Salesforce a “valet key” for limited access. That’s the goal with any of these. Not your keys to everything: a key that opens only what this integration needs.

When the other system supports OAuth client credentials, that’s usually the choice. Chapter 12 goes through every flow and when to use it.

There’s one more choice on the principal: named principal or per user. A named principal is one identity for everyone: every call signs in as the same integration account on the other side. Per user means each Salesforce user signs in as themselves, so the other system knows who did what. Most system-to-system integrations use a named principal.

Dial It In Once

There are a lot of little settings in this: the named credential, the external credential, the principal, the custom headers, the permission set. You don’t need to memorize them all. But to do the job, you’re going to hit these little stumbling blocks. It’s one of those things you dial in once, and then you don’t touch it again for a year. Then you come back to it, and you’ve forgotten how.

So write it down: which named credential calls which system, which external credential it uses, which principal, which permission set, who owns the secret on the other side, and when it expires. Chapter 1 asked of every arrow what happens when it fails. When this one fails at two in the morning, this note is what the person on call will need.

And here’s the part admins like. When you deploy from a sandbox to production, the named credential and the external credential deploy, but the secrets don’t. They stay out of the deployment, and you enter them in each org (Named Credentials: Get Started (opens in a new tab); its packaging guide covers the “sensitive access tokens that can’t be packaged”). So production’s secret is never sitting in a sandbox, or in source control.

What They Replace

Named credentials had an earlier version. In Winter ‘23, Salesforce introduced the current one, and in its own words: “Legacy named credentials are deprecated and will be discontinued in a future release” (Named Credentials: Get Started (opens in a new tab), checked 2026-11-01). If you open an older org and see a named credential with the password right on it, and no external credential, that’s the legacy kind. Build anything new on the current one.

And remote site settings? A callout to a named credential doesn’t need one. In Salesforce’s words, it “manages all authentication… so that your code doesn’t have to,” and you “can also skip remote site settings” for that site (Named Credentials as Callout Endpoints (opens in a new tab), Apex Developer Guide, checked 2026-11-01). You’ll still see them in older orgs. Chapter 16 is the history of both.

That’s the difference in one line. A remote site setting is an allow list for the whole org. A named credential is an allow list that also knows who’s leaving, and holds the keys to get in on the other side.

Named credentials have a bigger barrier to entry than a remote site setting. They seem cumbersome at first. But what they buy you is a lot of power.

What an Architect Decides Here

• For every system Salesforce calls, one named credential, with a name that says what it is.
• How each one signs in to the external system: OAuth client credentials when the other side supports it, a password only when nothing better exists.
• Named principal or per user: one integration identity on the other side, or each user as themselves.
• Which permission set may use it, and who is in it.
• Who owns each secret, where it came from, when it expires, and who sets it in each org after a deployment.

Beyond the exam: what AI changes. When AI writes a callout for you, the first thing to check is where it put the address and the secret. It will often write the URL straight into the code, or a key in a header, because that’s what its examples show. Ask it to use a named credential instead. It will, in seconds, but you have to know to ask.

Explore

• Salesforce Developers, Named Credentials: Get Started (opens in a new tab), checked 2026-11-01.
• Salesforce Help, Authentication Protocols for Named Credentials (opens in a new tab), checked 2026-11-01.
• Apex Developer Guide, Named Credentials as Callout Endpoints (opens in a new tab), checked 2026-11-01.
• The next module, External Services From an OpenAPI Spec: the protocol half, from the contract.