Salesforce Named Credentials: Secure API Callouts Without Hardcoded Secrets
Every Salesforce org eventually needs to talk to something outside Salesforce — a payment gateway, an internal API, a shipping service. The first version of that integration usually looks the same: an endpoint URL pasted into Apex, a username and password tucked into a custom setting, and a quiet hope that nobody ever looks too closely.
Named Credentials exist so you never have to do that again.
What a Named Credential Actually Does
A Named Credential is a single named definition that bundles three things: the base URL of the external system, the authentication scheme, and the credentials themselves. Your Apex code refers to the credential by name — callout:My_External_API — and Salesforce handles the rest: building the full URL, attaching the auth header, and refreshing tokens when the scheme supports it.
The important part is what your code never sees. Secrets live in the credential record, not in your source. That means no passwords in version control, no credentials visible in debug logs, and no frantic search-and-replace when a password rotates.
The Setup, Step by Step
There are two records to create, and the order matters.
1. Create an External Credential. This is where the authentication lives. Pick the protocol your system expects — basic auth, OAuth 2.0, JWT, or a custom header — and fill in the identity details. For OAuth flows, the external credential also stores the token endpoint and handles the token exchange.
2. Create the Named Credential. Point it at the base URL (for example https://api.example.com) and link it to the external credential you just made. Give it a clear, descriptive name, because that name is what developers will type in Apex for years.
3. Grant access with a permission set. Users can only use a Named Credential if a permission set grants them access to its external credential. This is the step most people skip and then spend an hour debugging — a callout that works for the admin fails for everyone else, and the error message will not tell you why.
Calling It From Apex
Once the credential exists, the callout is almost boring:
HttpRequest req = new HttpRequest(); req.setEndpoint('callout:My_External_API/orders/12345'); req.setMethod('GET'); HttpResponse res = new Http().send(req); Notice what is missing: no URL string, no Authorization header, no credential handling at all. The callout: prefix tells Salesforce to resolve the named credential, attach whatever auth the external credential defines, and send the request.
When you write Apex test classes, remember that callouts need a mock — Named Credentials do not change that rule, but they do make the mock simpler, because your test only has to assert against the named endpoint, not a hardcoded URL.
The Gotchas Worth Knowing
Callout limits still apply. Named Credentials do not raise the 100-callout-per-transaction limit or the 120-second timeout. If you are making many calls, think about batching or queueing the work — the same discipline you would apply to any governor-limit-sensitive code.
The URL is a base, not the whole path. The named credential holds the domain and base path; your Apex appends the resource path. Keep the base stable and build the resource path dynamically.
Rotate secrets at the credential, not in code. When a vendor rotates an API key, you update one record in Setup. No deployment, no code change, no weekend emergency release.
Per-user authentication is an option. For systems where each Salesforce user has their own external identity, an external credential can be configured per user instead of per org. This is the right call for integrations where actions should be attributed to the person, not the org.
If your org is adopting AI-assisted development, the same "keep secrets out of code" discipline matters even more — our guide to setting up Claude Code for Salesforce covers how to keep your development workflow clean while tools generate more of your code.
Why This Is Worth Doing Now
Retrofitting Named Credentials into an existing integration is a small job: create the two records, swap the endpoint strings for callout: references, and delete the hardcoded secrets. The payoff is permanent — every future integration starts from a secure pattern, every secret rotation is a one-record change, and your codebase stops being a place where credentials go to leak.
Start with the integration you trust the least. The one with the password in a custom setting that everyone knows about and nobody wants to touch. That is exactly the one Named Credentials were built for.
Originally published at Way2Force.
