How to set up Header based API Key authentication in External Services?

Hola! 😀

Passing custom headers, especially for authentication purposes, has been one of the most requested features by External Services users. Thanks to latest enhancements introduced in Winter ’23 for Named credentials, we can now pass custom headers while making callouts to external systems.

Let’s see how the set up would look like.

Quick context; in Winter ’23, Salesforce has completely reimagined the set up process for Named Credentials and they have introduced a new entity called External Credentials. So to create a Named Credential, you first need to create an External Credential.

NOTE: You can still create Named Credentials the old way. More info on this in the future post(s). 🙂

Let’s begin!

Step 1: Create External Credential.

• Go to Setup -> Named Credentials.

• Click on the External Credentials subtab, then click New.

• Enter a descriptive Label.

• Enter a developer Name.

• Set the Authentication Protocol to Custom.

• Click Save.

Step 2: Create Permission Set Mapping to store the API key.

• When viewing the External Credential, click New under Permission Set Mappings.

• Select a Permission Set that users will need to access this secret value. (Note: you may want to create a new Permission Set for this purpose.)

• Set the Sequence Number in case a user happens to have multiple Permission Sets used in multiple Permission Set Mappings. This number determines which mapping “wins” and gets used for the callout, sorted from lowest to highest.

• Leave the Identity Type set to Named Principal. This indicates that Salesforce users will share the same API key, and they don’t have unique access to the external service.

• Click Add to create an Authentication Parameter, and enter a suitable Name. The Name is a developer name that will be used in a later step.

• Paste in the API key as the Value of the Authentication Parameter.

• Click Save.

IMPORTANT NOTE: The Value in the Authentication Parameter is stored as encrypted values in the User External Credentials sObject. Any user that will make callouts needs Create, Read, Update and Delete access to this object. The record manipulation is managed by the platform—users can’t navigate a record detail page for a User External Credential and view raw tokens—but object access still needs to be explicitly granted.

Step 3: Adding Custom Header

• When viewing the External Credential, click New under Custom Headers.

• Enter the Name of the header as required by the external service (say, API-Header-Key for example).

• Enter the following Value:{!$Credential.FP_PublicResourceAuth.APIKey}, where FP_PublicResourceAuth is the name External Credential API name and APIKey is the header name used in the Permission Set Mapping.

• Leave the Sequence Number set to the default, since we don’t need to worry about the order of headers in this case.

• Click Save.

NOTE: Custom Headers support Merge Fields and Formula functions.

Step 4: Create the Named Credential.

• Click the Named Credentials subtab, then click New.

• Enter a descriptive Label.

• Enter a developer Name.

• Set the URL to the correct endpoint.

• Select the External Credential created in the prior step.

• For this example, it’s important to uncheck the Generate Authorization Header setting. Instead, this will be handled by the Custom Header we defined in the prior steps.

• As we’re not using any formula functions in header values, we should leave the Allow Formulas in HTTP Header setting unchecked.

• Click Save.

And voila! You can now use this Named Cred in your External Services to make the callouts.

I’ll be posting some more content around the new Named Credentials, so stay tuned if you’re interested.

Hope you find this one useful! Catch you in the next one! ✌ And thank you for being an awesome reader! Subscribe to this blog for receiving all the latest updates straight to your inbox. 🙂