Salesforce Named Credentials

A hotel keeps spare room keys in a locked cabinet. Staff use the keys without memorising any codes. Named Credentials give Salesforce the same convenience. They store the address of an outside service and the login details in one secure place. Apex code, flows, and external services point to the name, and Salesforce handles authentication behind the scenes.

The Problem Named Credentials Solve

Developers once wrote web addresses, usernames, and passwords directly in Apex code. That habit created three problems.

• A password in code is visible to anyone who can read the class.
• A password change forces a code deployment.
• Sandboxes and production need different addresses, so every move requires edits.

Named Credentials remove all three problems. The code uses a label, and admins manage the sensitive values in Setup.

Building Blocks of the Modern Model

Salesforce splits the setup into two linked parts.

Part	Stores
Named Credential	The service address (URL) and which External Credential to use
External Credential	The authentication method and the principals that hold login details
Permission Set Mapping	Which users may use the credential through a principal

Apex Code
   |  callout:Courier_API/track
   v
+--------------------+
|  Named Credential  | --> URL: https://api.courier.example
+--------------------+
   |
   v
+--------------------+
| External Credential| --> Auth: OAuth 2.0 / API key
|   + Principal      | --> Secret values stay encrypted
+--------------------+
   |
   v
Permission Set grants access to the principal

Authentication Options

• No authentication for public services.
• Basic authentication with a username and password.
• API key or custom header for services that require a token.
• OAuth 2.0 for services that issue time-limited access tokens.
• JWT for server-to-server connections.

OAuth tokens refresh automatically, so code never handles expiry logic.

Create a Named Credential: Step by Step

1. Open Setup and search for Named Credentials.
2. Open the External Credentials tab and click New.
3. Enter a label such as Courier Credential, and choose an authentication protocol.
4. Add a Principal and enter the secret values, such as the API key.
5. Save, and create a Permission Set that enables the principal.
6. Assign the permission set to the users or the integration user who run the callouts.
7. Return to the Named Credentials tab and click New.
8. Type a label and name, such as Courier_API, and paste the service URL.
9. Select the External Credential created above.
10. Save and test the connection.

Using the Credential in Apex

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:Courier_API/track?id=PK1001');
req.setMethod('GET');
HttpResponse res = new Http().send(req);

The prefix callout: tells Salesforce to look up the Named Credential. The code contains no address and no password. Salesforce adds the authentication header before the request leaves.

Using the Credential in Flow

External Services let a flow call an API through a Named Credential without any code. An admin registers the service with an OpenAPI description, and the actions appear in Flow Builder as drag-and-drop elements.

One Name, Different Environments

Deployments carry the Named Credential name between orgs. Each org stores its own URL and secret. A sandbox can point to a test server while production points to the live server, and the Apex code stays identical.

Same code:  callout:Courier_API/track
                  |
    +-------------+-------------+
    |                           |
Sandbox org                Production org
URL: test.courier.example  URL: api.courier.example
Key: test key              Key: live key

Legacy Named Credentials

Older orgs contain legacy Named Credentials that hold the URL and login details in one record. The legacy format still works, and Salesforce encourages new work to use the External Credential model for better permission control.

Security Benefits

• Secrets stay encrypted and hidden from developers.
• Permission sets control who can trigger authenticated callouts.
• Admins rotate a key in one location.
• Audit teams review one list of external connections.

Best Practices

• Create a dedicated integration user for system-to-system calls.
• Use clear names that match the external service.
• Grant the smallest permission set needed.
• Document each credential, its owner, and its renewal date.
• Remove credentials for services that the company no longer uses.