Can Named Credential Merge Fields Be Used in URLs?

Question:

I have a Named Credential defined as follows:

• Name: Test_Credential
• URL: https://www.somesite.com
• Identity Type: Named Principal
• Authentication Protocol: Password Authentication
• Username: foobar
• Password: mySomeSiteDeveloperKey
• Generate Authorization Header: FALSE
• Allow Merge Fields in HTTP Header: TRUE
• Allow Merge Fields in HTTP Body: TRUE

The service I am trying to authenticate against requires passing the username and developer key as URL parameters. I attempted to use Named Credential merge fields to pass these parameters, but debugging the request shows that the merge fields are not replaced before the request is sent. I tried constructing the endpoint in these two ways:

req.setEndpoint('callout:Test_Credential/api/action?id={!$Credential.Password}&account={!$Credential.UserName}');

req.setEndpoint('callout:Test_Credential/api/action' + '?id=' + '{!$Credential.Password}');

Both methods result in the placeholders ({!$Credential.Password} and {!$Credential.UserName}) being sent as-is, without merging. Is it possible to use Named Credential merge fields in the URL parameters? If not, is there a workaround?

Additionally, is there a way to inspect the fully constructed HTTP request to better debug such issues?

Answer:

Unfortunately, Named Credential merge fields cannot be used directly in the URL parameters of the endpoint. Merge fields are supported only in HTTP headers and the HTTP body, as explicitly allowed by the Named Credential settings (Allow Merge Fields in HTTP Header and Allow Merge Fields in HTTP Body).

CRS Info Solutions is one of the premier institutes offering Salesforce training in Seattle. Enroll for free demo today.!!

To work around this limitation, consider the following approaches:

1.Use HTTP headers or the body instead of URL parameters:

Adjust your integration to include the username and developer key in the HTTP headers or body. For example, use application/x-www-form-urlencoded for a POST request:

req.setBody('id={!$Credential.Password}&account={!$Credential.UserName}');

2.Modify the server to accept headers or body parameters:

If you control the server, configure it to accept authentication details through headers or the body instead of query strings. Sending sensitive data like passwords in the URL is a significant security risk, as URLs can be logged or exposed unintentionally.

req.setMethod('POST');
req.setHeader('Content-Type', 'application/x-www-form-urlencoded');
req.setBody('id={!$Credential.Password}&account={!$Credential.UserName}');
req.setEndpoint('callout:Test_Credential/api/action');

3.Manually construct the URL with credentials:

If the server strictly requires authentication in the URL, you must retrieve the username and password programmatically from the Named Credential and construct the endpoint dynamically. This approach negates some of the benefits of using Named Credentials but works as a last resort.

String username = System.Label.MyCredentialUserName; // Fetch from Custom Metadata or a Protected Custom Setting
String password = System.Label.MyCredentialPassword;

req.setEndpoint('https://www.somesite.com/api/action?id=' + EncodingUtil.urlEncode(password, 'UTF-8') + '&account=' + EncodingUtil.urlEncode(username, 'UTF-8'));

This method is not recommended unless necessary, as it bypasses Named Credential security and may expose credentials in logs.

4.Inspect the HTTP request:

Point your endpoint to a debugging tool that captures and displays incoming requests. This allows you to review the headers, body, and parameters sent by Salesforce for troubleshooting.

For example:

req.setEndpoint('https://httpbin.org/get');
req.setHeader('X-API-KEY', '{!$Credential.Password}');
req.setHeader('X-USERNAME', '{!$Credential.UserName}');

If possible, re-evaluate the API design to avoid passing sensitive credentials in URL parameters. This practice exposes the data to unnecessary risks, such as logging and caching, and is generally considered a poor security practice.

Key Takeaways

1. Named Credential merge fields cannot be used in the URL.
2. Use headers or body for passing authentication details.
3. If the API strictly requires credentials in the URL, retrieve them manually (though this is not secure).
4. Debug the request using tools like httpbin.org to inspect what Salesforce is actually sending.

Always aim to use the most secure approach, avoiding credentials in URLs whenever possible.

Accelerate Your Salesforce Career in Seattle

Elevate your Salesforce skills with expert-led  Salesforce online training  in Seattle, tailored for both beginners and professionals. Gain practical experience through real-world projects and master cloud-based CRM solutions with guidance from certified instructors. Unlock exciting career opportunities and become a Salesforce expert with comprehensive, hands-on learning at CRS Info Solutions.

CRS Info Solutions is a leading Salesforce training in Seattle, offering a thorough, real-time project-based curriculum. Our courses cover Salesforce Admin, Developer, Integration, Marketing Cloud, CPQ, and Lightning Web Components (LWC). With expert instructors offering hands-on training, we ensure you’re well-prepared for real-world challenges. Join us now to become a certified Salesforce professional and take the next step in your career.

Enroll today for a free demo at CRS Info Solutions, Seattle!!!