Named Credentials in Salesforce:
Setup & Best Practices

Named Credentials solve a real security problem: where do you store API keys and tokens when deploying Salesforce across environments? Hard-coding them in Apex is dangerous. Custom Settings with credentials in plaintext is almost as bad. Named Credentials are the right answer.

What Named Credentials Do

A Named Credential stores an endpoint URL plus authentication details (API key, OAuth token, Basic auth) in a secure, metadata-deployable way. In your Apex callout, you reference it by name — Salesforce resolves the URL and injects authentication headers at runtime. Developers never see the actual credentials.

Legacy vs. New Named Credentials

In Summer '22, Salesforce split Named Credentials into two concepts:

• Named Credential — stores the endpoint URL and protocol; references an External Credential for auth
• External Credential — stores the authentication method and secrets (API key, OAuth client ID/secret, certificate)

Legacy Named Credentials (pre-Summer '22 setup page) bundle both into one. They still work but are not recommended for new implementations. Use the new split model.

Setting Up a Named Credential (New Model)

Step 1: Create an External Credential

Setup → Named Credentials → External Credentials → New. Choose your authentication protocol:

• Custom (API Key) — for simple Bearer token or key-in-header auth
• OAuth 2.0 — for standard OAuth flows; Salesforce handles token refresh automatically
• Basic — username/password (avoid if the API supports OAuth)

Step 2: Create a Named Credential

Setup → Named Credentials → Named Credentials → New. Set the Label, Name (used in Apex), URL, and select your External Credential.

Step 3: Grant Permission

On the External Credential, add a Permission Set Mapping. Assign the mapped Permission Set to the users or integration profiles that need callout access.

Using It in Apex

HttpRequest req = new HttpRequest();
// The Named Credential name replaces the full URL
req.setEndpoint('callout:My_API/v1/endpoint');
req.setMethod('GET');
// No Authorization header needed — injected automatically
Http http = new Http();
HttpResponse res = http.send(req);

The callout: prefix tells Salesforce to resolve this against your Named Credentials. The path after the credential name (/v1/endpoint) is appended to the stored base URL.

Per-User vs. Org-Wide Credentials

In the External Credential Principal settings, you can set scope to Org (one shared credential for all callouts) or Per User (each Salesforce user authenticates individually via OAuth). Per-user is required for APIs where the external system needs to act as the specific user, not a shared service account.

OAuth 2.0 Setup Notes

When using OAuth 2.0 Client Credentials flow (most common for server-to-server integrations):

1. Register Salesforce as an OAuth app in the target system; copy Client ID and Client Secret
2. In the External Credential, set Protocol = OAuth 2.0, Flow = Client Credentials
3. Enter the Token Endpoint URL, Client ID, and Client Secret
4. Salesforce fetches and caches the token, refreshing it before expiry automatically

Deployment Across Environments

Named Credentials are deployable via change sets and the Metadata API. However, credential secrets (API keys, client secrets) are not deployed — they must be re-entered in each environment. This is by design for security. Document which secrets go where and rotate them on schedule.