When a Salesforce Named Credential is used with a Salesforce SOAP API endpoint, the credential merge field {!$Credential.OAuthToken} does not automatically refresh the OAuth token when it expires. This is because Named Credentials rely on the external service returning HTTP 401 to trigger the token refresh flow. However, when a Salesforce SOAP API session is expired, the SOAP response returns HTTP 500 (not HTTP 401), so the automatic refresh is never triggered.
The following example demonstrates a callout using a Named Credential with the SOAP API. When the token is expired, the SOAP API response contains <sf:exceptionCode>INVALID_SESSION_ID</sf:exceptionCode> rather than HTTP 401, which prevents the Named Credential from auto-refreshing the token.
Example Callout (Apex):
The code sets the endpoint using the Named Credential callout prefix (callout:sfa/services/Soap/...), sets the Content-Type to text/xml; charset=utf-8, and embeds {!$Credential.OAuthToken} in the SOAP envelope's SessionHeader. When the token expires, the response is INVALID_SESSION_ID rather than a token refresh.
HttpRequest req = new HttpRequest();
req.setEndpoint('callout:sfa/services/Soap/u/37.0/00DA0000000Ah7w');
req.setMethod('POST');
req.setHeader('Content-Type','text/xml; charset=utf-8');
req.setHeader('SOAPAction','wewew');
String payload='<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:partner.soap.sforce.com">'+
'<soapenv:Header>'+
'<urn:SessionHeader>'+
'<urn:sessionId>{!$Credential.OAuthToken}</urn:sessionId>'+
'</urn:SessionHeader>'+
'</soapenv:Header>'+
'<soapenv:Body>'+
'<urn:query>'+
'<urn:queryString>select id from contact limit 10</urn:queryString>'+
'</urn:query>'+
'</soapenv:Body>'+
'</soapenv:Envelope>';
System.debug('');
req.setBody(payLoad);
Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody()); The reason for this behavior is that Salesforce SOAP API returns HTTP 500 for expired sessions, not HTTP 401. Named Credentials can only automatically refresh the OAuth token when the service returns HTTP 401.
To force the Named Credential to refresh the OAuth token, first make a dummy REST API call to the same Named Credential. REST API returns HTTP 401 on token expiry, which triggers the Named Credential refresh flow. After the refresh completes, re-execute the SOAP API callout — it will now use the refreshed token.
Http h = new Http();
HttpRequest req = new HttpRequest();
req.setEndpoint('callout:sfa/services/data/v22.0/query/?q=SELECT+id+from+contact');
req.setMethod('GET');
HttpResponse res = h.send(req);
000381864

We use three kinds of cookies on our websites: required, functional, and advertising. You can choose whether functional and advertising cookies apply. Click on the different cookie categories to find out more about each category and to change the default settings.
Privacy Statement
Required cookies are necessary for basic website functionality. Some examples include: session cookies needed to transmit the website, authentication cookies, and security cookies.
Functional cookies enhance functions, performance, and services on the website. Some examples include: cookies used to analyze site traffic, cookies used for market research, and cookies used to display advertising that is not directed to a particular individual.
Advertising cookies track activity across websites in order to understand a viewer’s interests, and direct them specific marketing. Some examples include: cookies used for remarketing, or interest-based advertising.