Fix Guide

How to Fix Salesforce Named Credential Authentication Failures

Step-by-step fix guide with AI-powered diagnosis from BuildForce.

Salesforce Named Credentials fail when the underlying External Credential's OAuth tokens expire and the configured Identity Type (Per User vs Named Principal) prevents automatic refresh, when an admin rotates the External Credential's client secret without re-authorizing principals, or when the named credential is set to mTLS and the certificate has rotated out of the Salesforce CertificateAndKey store. The fix is to inspect the External Credential's Principal status, re-authorize from the Setup UI, and configure the Permission Set Group to map users to the right authentication principal.

External Credential PrincipalPer-User IdentityPermission Set Auth MapCallout 401

Get AI-Powered Diagnosis See Pricing

Symptoms

Apex callouts via callout:MyNamedCred returning 401 Unauthorized

External Services actions failing with 'Named credential auth has expired'

Per-user named credential prompting users to re-authenticate every session

Connected app callouts failing only for some users (not others) on the same named credential

Scheduled Apex jobs failing with 'No valid principal' after a Salesforce release

mTLS callouts failing with SSL handshake errors after a cert rotation

Root Causes

External Credential principal expired and not re-authorized

Named Credentials in Spring '23+ use External Credentials as the auth provider. Each External Credential has Principals (Per User or Named Principal). If the Named Principal's OAuth refresh token expires, the principal moves to 'Configured' state and callouts fail until an admin re-authorizes from the Setup UI.

Permission set not granting access to the External Credential principal

Users must have a Permission Set or Permission Set Group that includes 'External Credential Principal Access' for the specific principal. Without it, callouts return 401 even though the credential itself is valid.

Per User identity without first-time authorization

Per-User External Credentials require each user to authorize on first use. If the user is a service account or scheduled job runner who can't interactively authorize, callouts fail. Switch to Named Principal for service contexts.

Client secret rotated on remote system without updating External Credential

When the remote system (Salesforce destination org, HubSpot connected app, etc.) rotates its OAuth client secret, the External Credential's stored secret is stale. Refresh attempts return invalid_client and the principal moves to broken state.

mTLS certificate expired in CertificateAndKey

Named Credentials configured for mTLS reference a Salesforce-managed certificate. If the cert expires (typically 1-year default) and isn't rotated in Setup → Certificate and Key Management, all callouts fail with SSL handshake errors.

How to Fix It — Step by Step

Check the External Credential principal status

Setup → Named Credentials → External Credentials → [Your Credential]. The Principals tab shows each Principal's Authentication Status. Anything other than 'Configured' (with green check) needs action.

Re-authorize the failing principal

Click 'Edit' on the failing Principal and click 'Authenticate'. For Named Principal, this opens an OAuth flow you complete as an admin. For Per User, each user must authorize from their own User Settings → Authentication Settings for External Systems.

Verify Permission Set assignments include the External Credential

Open the Permission Set that should grant callout access. Under External Credential Principal Access, confirm the External Credential's Principal is listed. Add it if missing, then re-test the callout.

Example

SELECT Id, Label, ExternalCredentialId, PrincipalType, PrincipalName 
FROM ExternalCredentialPrincipal 
WHERE ExternalCredential.DeveloperName = 'YourCredential'

Switch service-context callouts from Per User to Named Principal

If the failing principal is Per User and the caller is a service user (scheduled Apex, integration user), edit the Principal Type to Named Principal. This is the right pattern for non-interactive callers.

Test the callout via Anonymous Apex

Run a minimal HTTP callout against the Named Credential. The response code and any error body tells you whether the issue is auth (401), endpoint (404), or downstream (500 from remote system).

Example

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:MyNamedCred/api/health');
req.setMethod('GET');
HttpResponse res = new Http().send(req);
System.debug('Status: ' + res.getStatusCode());
System.debug('Body: ' + res.getBody());

Rotate mTLS certificate before expiry

For mTLS Named Credentials, set a renewal reminder 30 days before cert expiry. Generate a new self-signed or CA-signed cert in Setup → Certificate and Key Management, update the remote system's trust store, then point the Named Credential to the new cert and remove the old one.

Monitor External Credential health with a daily check

Set up a scheduled Apex or BuildForce health check that queries ExternalCredentialPrincipal status daily and alerts on any non-Configured state. Catching a broken principal within 24 hours prevents downstream integration failures.

Let BuildForce diagnose and fix this automatically

Instead of following manual steps, connect your org and let our AI identify exactly what's broken and how to fix it — in minutes.

Book a Demo

Common Questions

More answers about this issue and how to resolve it.

Stop debugging manually. Let AI do it.

BuildForce runs 200+ automated checks across your Salesforce org and tells you exactly what's broken and how to fix it.

Book a Demo View Pricing