--- schema_version: "1" id: f6a85f752da8bf3cfccc7a2bade33ab92b1be5acc022a93964943679d75efca8 title: Use API Keys in Custom Headers with Named Credentials collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/xcloud/264-0-0/nc_custom_headers_and_api_keys.md canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.nc_custom_headers_and_api_keys.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 69b7d95e77c8ae256d8d7e24279e96c13e2e0905de8ddab10cd7937a259c05c2 description: Web services often define their own authentication protocols using custom headers. For those cases, you can create a custom header for a named or external credential and use API keys as a password. products: - Security release: "264" --- # Use API Keys in Custom Headers with Named Credentials Web services often define their own authentication protocols using custom headers. For those cases, you can create a custom header for a named or external credential and use API keys as a password. ### Required Editions
Available in: both Salesforce Classic (not available in all orgs) and Lightning Experience
Available in: all editions
The named credentials schema includes support for authentication protocols like OAuth 2.0 and AWS Signature v4. Some web service providers have their own authentication protocols that use unique headers for authentication. In these cases, choose a `Custom` authentication protocol for your external credential, and use a custom header to authenticate to such systems. One common approach used by web service providers for custom authentication is _API keys_. Besides authentication, API keys can also be used for various HTTP-related services, such as caching or cookies. For named credentials, you can create a custom header that uses API keys as an authentication protocol, with the key’s secret value functioning as a password. Each web service can name its headers arbitrarily. Common names include `ACCESS_TOKEN`, `bearer`, `Client-ID`, `developer-token`, and `X-API-Key`. For the HTTP 1.x standard, a call using a (hard-wired) API key can look something like this. ``` GET https://example.com HTTP/1.1 Client-ID: abc123 ``` Here the API key `Client-ID` is also the name of the header, and _abc123_ is the value of the API key used for authentication. The name and the value are set by the authenticating system. Typically, you retrieve these parameters through the external system’s UI. The HTTP standard includes an `Authorization` header for authentication. By default, Salesforce named credentials use this standard authorization header. However, you can override the default and create a custom Authorization header. This example shows the `Authorization` header used with an API key. ``` GET https://example.com HTTP/1.1 Authorization: Client-ID abc123 ``` The general steps to use API keys with named credentials are: 1. Create an external credential, setting the Authentication Protocol to Custom. An external credential stores authentication and authorization information and is used by named credentials. 2. Store the API key as an authorization parameter in a principal. 3. Create a custom header for the external credential. The header references the API key. 4. Create a named credential that references the external credential. ## Store an API Key as an Authentication Parameter in a Principal We strongly recommend storing API key authentication parameters as part of an external credential principal. The API key is a secret value. Authentication parameters are expected to contain secrets and are stored in an encrypted manner consistent with other sensitive information. Additionally, access to the secrets is granted explicitly using a principal. A principal links an external credential to permission sets and profiles. By adding authentication parameters to a principal, you enable different groups of Salesforce users to use different authentication tokens to call the same external service. 1. Create an external credential and set the Authentication Protocol field to **Custom**. For instructions on creating and configuring external credentials, see [Create or Edit a Custom Authentication External Credential](https://help.salesforce.com/s/articleView?id=xcloud.nc_create_edit_custom_auth_ext_cred.htm&release=264.0.0&type=5 "To account for web service providers that use unique headers for authentication, create an external credential that uses the Custom authentication protocol."). In this example, the external credential is named `MyCustAuthExternCred`. ![New external credential with custom authentication](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-security-264-0-0-production-enus/8cecd769-ab2d-4e07-addf-c4f2927925e1/security/images/user_api_access/apikeys_new_extern_cred_01.png) 2. On the external credential’s page, scroll to Principals. 3. To create a principal, click **New**, and set these fields. ![Principal mapping for custom authentication](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-security-264-0-0-production-enus/8cecd769-ab2d-4e07-addf-c4f2927925e1/security/images/user_api_access/244_create_custom_principal_01.png) Parameter Name A name for the principal, such as Admin or Marketing Team. Sequence Number This number determines which mapping is used for the callout, sorted from lowest to highest. Set the sequence number in case a user has multiple permission sets used in multiple principals. Identity Type Custom authentication uses the Named Principal identity type. Named Principal indicates that Salesforce users share one API key, and they don’t have unique access to the external service. You can’t change the identity type for Custom authentication. ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-security-264-0-0-production-enus/8cecd769-ab2d-4e07-addf-c4f2927925e1/images/icon_note.png) Note At this time, only the OAuth protocol supports unique per-user access to a remote system. In that case, each user logs in separately before the integration works in their user context. Name The name for the authentication parameter. In this example, the name is `MyClientId`. Value The API key value. In many cases, you get the API key from the web service’s UI. 4. Map the principal to a permission set or profile. See [Enable External Credential Principals](https://help.salesforce.com/s/articleView?id=xcloud.nc_enable_ext_cred_principal.htm&release=264.0.0&type=5 "Principals link an external credential to permission sets or user profiles so that users can make callouts using the named credential. At run time, Salesforce ensures that the user has the permission set before accessing the remote system."). You can map a principal to multiple permission sets, permission set groups, or profiles. ## Use API Keys in a Custom Header After you add API keys to a principal, you can use those keys in a custom header. 1. On the external credential that you created, scroll to Custom Headers and click **New**. 2. Fill in the fields for the custom header. ![Create a custom header with fomulas](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-security-264-0-0-production-enus/8cecd769-ab2d-4e07-addf-c4f2927925e1/security/images/user_api_access/apikeys_create_custom_header_01.png) Name The name of the standard HTTP request header as required by the external service. In this case we’re performing authentication, so we use the HTTP standard name Authorization. Value The API key name and value. It can be a literal or a programmatic expression. The value can be expressed programmatically with merge fields and formulas. For instance, the value can take this form. ``` {!'Client-ID ' & $Credential.Container.ParameterName} ``` In this example, the literal string `Client-ID` is concatenated with the API key, and the expression resolves as: ``` {!'Client-ID ' & $Credential.MyCustAuthExternCred.MyClientId} ``` Formulas can be used in header values via the `{!`FormulaGoesHere`}` syntax. Anything inside `{!}` is evaluated as a Salesforce formula. Formulas provide significant power and flexibility to craft header values without coding. Merge fields provide access to encrypted values via the `$Credential.`Container.ParameterName syntax. In this example Container is the external credential `MyCustAuthExternCred`. ParameterName is the principal authentication parameter `MyClientId`, which was mapped to the API key value. Sequence Number This number determines which header “wins” and gets used for the callout, sorted from lowest to highest. If you’re not worried about collisions with other headers, leave this field as the default. The external credential now shows the custom header with a reference to the authorization parameter that contains the API key. ![External credential with custom authentication](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-security-264-0-0-production-enus/8cecd769-ab2d-4e07-addf-c4f2927925e1/security/images/user_api_access/apikeys_extern_credential_01.png) If `Client-ID` is _abc123_, the resulting callout looks like this. The named credential appends Authorization: as the header name. ``` GET https://example.com HTTP/1.1 Authorization: Client-ID abc123 ``` ![Tip](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-security-264-0-0-production-enus/8cecd769-ab2d-4e07-addf-c4f2927925e1/images/icon_tip.png) Tip Make sure you enable user external credentials for your users who are using named credentials. See [Enable User External Credentials](https://help.salesforce.com/s/articleView?id=xcloud.nc_user_external_credentials.htm&release=264.0.0&type=5 "Tokens for named credential callouts are encrypted and stored in the User External Credential object. Any user performing an authenticated callout needs profile- or permission set-based access to user external credentials. Most standard permission sets and profiles have access to the User External Credentials object by default. For the guest user profile, and for some custom permission sets and profiles, you must assign User External Credentials object permissions manually."). ## Use API Keys with a Named Credential After you’ve created an external credential that uses API keys, it can be referenced by a named credential. 1. Disable **Generate Authorization Header** in the named credential. Disabling this option ensures that the named credential uses the custom `Authorization` header that you created. 2. In that named credential, make sure that **Allow Formulas in HTTP Header** is enabled. A callout using this named credential returns successfully because it has the correct `Authorization` header. If the tokens expire or the URL changes, no changes to Apex code are needed. In addition to Apex, the credential can be used in no-code tools such as External Services that provide integration with Flow. #### See Also - [Create Named Credentials and External Credentials](https://help.salesforce.com/s/articleView?id=xcloud.nc_named_creds_and_ext_creds.htm&release=264.0.0&type=5 "To simplify the setup of authenticated callouts, create an external credential to specify an authentication protocol and then specify a named credential as the callout endpoint. Add custom headers to cover more use cases and security requirements. Use a permission set or profile to grant access so that users can make authenticated callouts. You can create and configure named credentials programmatically or through the Salesforce UI.") - [Use Custom Headers with Credentials](https://help.salesforce.com/s/articleView?id=xcloud.nc_cred_custom_headers.htm&release=264.0.0&type=5 "Add custom headers to external credentials to cover more use cases and security requirements. With custom headers, you can set your own parameters for authentication.") - [Calculate Field Values With Formulas](https://help.salesforce.com/s/articleView?id=platform.customize_formuladef.htm&type=5&language=en_US) - [_Apex Developer Guide_: Merge Fields for Apex Callouts That Use Named Credentials](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts_named_credentials_merge_fields.htm)