The Old Way vs. The New Way

For years, making an authenticated callout from Salesforce meant: store credentials in Custom Settings or Custom Metadata, concatenate auth headers in Apex, hope nobody caught the secret in a debug log, repeat.

Named Credentials replaced that with a managed, auditable, admin-configured alternative. The 2024 overhaul added External Credentials and Credential Principals, splitting “where you call” from “how you authenticate.” The result is a cleaner, more flexible model that covers OAuth 2.0, JWT, basic auth, AWS signing, custom headers, and per-user tokens.

If you’re still storing API keys in Custom Metadata, this article is why you should stop.

The New Model

Three layers:

1. External Credential

Defines how to authenticate — the auth protocol, client ID/secret, token URL, scopes.

2. Named Credential

Defines where to call — the base URL, headers, and a reference to one or more External Credentials.

3. Credential Principal

Defines who the credentials represent — a per-user principal, a per-permission-set-group principal, or a single org-wide principal.

You assemble these three to describe a full integration endpoint.

Why the Split Matters

The old Named Credential combined auth and endpoint in one object. Switching auth methods meant recreating the credential.

With the split:

  • The same External Credential (your OAuth app registration) can be referenced by multiple Named Credentials (different endpoints in the same API).
  • Named Credentials can reference multiple External Credentials for fallback auth.
  • Principals can be per-user or shared — your choice, not locked into the credential shape.

Calling From Apex

Once configured, the Apex call is trivial:

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:MyExternalApi/orders');
req.setMethod('GET');

HttpResponse res = new Http().send(req);

The callout:MyExternalApi/orders syntax tells Salesforce to resolve the named credential MyExternalApi, apply its auth, and make the call. Auth headers, base URL, and token refresh all happen automatically.

Protocols Supported

OAuth 2.0. Client credentials, authorization code, refresh tokens. Most modern APIs. External Credential stores client ID/secret and token URL; Salesforce handles token lifecycle.

JWT. For APIs that accept signed JWTs as bearer tokens. Configure signing key in a Certificate metadata; Salesforce signs per call.

AWS Signature v4. For calling AWS services directly. Configure access key, secret key, region, service. Salesforce signs requests per AWS’s protocol.

Basic Auth. Username/password. Use only when the target doesn’t support better.

Custom Headers. For API-key-in-header patterns. Specify the header name and value.

Certificate (mTLS). Mutual TLS with client certs stored as metadata.

If your API requires something unusual, the “Custom” auth type with Named Principal and custom headers usually covers it.

Per-User vs. Shared Credentials

Shared credentials. One principal for all callers. Simple. Appropriate for service-to-service integrations.

Per-user credentials. Each user has their own tokens. Use when the external API is user-scoped — Gmail, individual Slack accounts, personal OAuth connections.

The per-user pattern is how you build “connect your GitHub” or “connect your Slack” user-facing integrations without leaking one user’s tokens to another.

Setting Up OAuth 2.0 Client Credentials

A common case: server-to-server OAuth where Salesforce authenticates as itself (not on behalf of a user).

  1. External Credential:
    • Authentication Protocol: OAuth 2.0
    • Authentication Flow Type: Client Credentials with Principal
    • Scope: as required by the API
    • Identity Type: Named Principal
  2. Principal:
    • Parameter Name: access_token
    • Client ID: (from the external API)
    • Client Secret: (from the external API)
  3. Named Credential:
    • Label: MyExternalApi
    • URL: https://api.example.com
    • External Credential: (link to the one above)

Test with callout:MyExternalApi/status in Apex. Monitor the token refresh behavior.

Permission Set Gating

Access to use a Named Credential is gated by permission set. Without the permission, callouts fail with a credential-not-authorized error.

This is a safety feature. A leaked API key in Custom Metadata was available to any Apex that read the setting. A Named Credential is only usable by code running as users with the right permission set.

Configure: Permission Set → External Credential Principal Access → select the principal.

Migration From Old Pattern

If you have Apex that manually builds auth headers from Custom Metadata:

  1. Create External Credential with the equivalent auth config.
  2. Create Named Credential pointing at the base URL.
  3. Add an External Credential Principal entry (for OAuth), or configure per-user principals.
  4. Grant permission set access to the principal.
  5. Refactor Apex to use callout:NamedCred/path syntax and remove the manual auth code.
  6. Delete the old Custom Metadata/Setting storing the secret.

Don’t skip step 6. The old secret is still a liability until it’s rotated and removed.

Debugging Tips

Callout fails with “Unauthorized”: the token didn’t refresh or wasn’t included. Check the External Credential principal — is the client secret right? Does the IdP accept the grant type?

Callout fails with “Credential not accessible”: the running user’s permission set doesn’t grant access to the principal. Grant it.

Auth works in Postman but not Salesforce: check scopes, check redirect URIs, check the auth flow type matches what the API expects.

Unreliable token refresh: some APIs return odd 4xx responses when tokens are near expiry. Salesforce’s auto-refresh handles most cases, but for picky APIs you may need to force refresh explicitly.

Monitoring

Setup → Named Credentials → your credential:

  • View the External Credential Principal’s last token refresh time.
  • View the principal’s authentication status.

Setup → Event Monitoring → Callout events:

  • Per-call logs of outbound requests.
  • Useful for auditing which users hit which endpoints.

Anti-Patterns

Hardcoding credentials in Apex. A lifetime of pain.

Storing secrets in Custom Metadata as strings. Better than hardcode, still bad.

Reusing one credential across very different APIs. Breaks the permission model.

No principal rotation. Client secrets should rotate periodically. Build a reminder.

Frequently Asked Questions

Can Flow use Named Credentials?

Yes. HTTP Callouts in Flow and External Services both leverage Named Credentials. Configure once, use in Apex and Flow.

Do Named Credentials work for Inbound calls?

No — they’re for outbound only. Inbound authentication uses Connected Apps and standard Salesforce auth flows.

Is there a cost?

No — Named Credentials are included in every edition.

Can I use Named Credentials for MuleSoft or external systems?

Yes. Any outbound callout from Salesforce (Apex, Flow, External Services) can use Named Credentials for auth.

Share