--- schema_version: "1" id: 71c6f35443a838c2fd47cdec30531f687608f102ab33cfdf630a87d87123d838 title: Use Cases for 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_header_use_cases.md canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.nc_custom_header_use_cases.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: aeec852c926be5cc98d3c985f80044f12b227f4ca643b91b1c1e76922502834d description: Custom headers are most often used for security or authentication purposes. The HTTP standard includes a commonly used, dedicated Authorization header. However, many use cases require something else. Two common use cases are per-user callouts and API keys. products: - Security release: "264" --- # Use Cases for Custom Headers with Named Credentials Custom headers are most often used for security or authentication purposes. The HTTP standard includes a commonly used, dedicated Authorization header. However, many use cases require something else. Two common use cases are per-user callouts and API keys. ### Required Editions
Available in: both Salesforce Classic (not available in all org) and Lightning Experience
Available in: all editions
Because named credentials operate in the HTTP world, parameter provision is implemented as an HTTP request accompanied by headers that act as additional inputs required by the service you’re calling. HTTP requests have a header and a body, and inputs can appear in both. It’s also common for inputs to appear in a URL as a query string. All three approaches have pros and cons. We discuss only headers here. ## Per-User Callouts Many systems respond to HTTP requests differently based on which user or role makes the request. For example, sometimes an integration to a company returns a personal phone number but only if the person whose phone number it is makes that callout request. However, a calling user in the company’s HR department can see any user’s salary, though the HR role must be specified. Here’s an example of a per-user callout that uses a custom header to identify the user by their email address. ``` GET https://example.com/getInfo?personId=my_username%40example.com/HTTP/1.1 X-Calling-User:my_username@example.com ``` As another example, Microsoft offers an enterprise-wide search service and returns different results based on the caller’s identity. Users don’t get results they’re not allowed to see. Salesforce named credentials support this service because admins can define headers such as `X-Calling-User` and substitute the value of the user making the callout, for example, `{!$User.email}`. The header is defined on an external credential. ![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 If you’re using a formula in a custom header in an external credential, and you choose Named Principal as your identity type, don’t use `$User` in the formula. ## API Keys API key refers to a programmatic password used in an HTTP request to identify a calling application attempting to access a given API. API keys have no strict standard, so anyone who builds an API can define their own headers, rules, and so on. Here’s an example of a callout that uses an API key. ``` GET https://example.com/api/11a5aea0?count=20 HTTP/1.1 X-API-Key: abc123 ``` `X-API-Key` is arbitrary, and some vendors use headers such as `Client-ID`. This example, for retrieving a random photograph, uses a mixture of `Client-ID` and the standard Authorization header. ``` GET https://example.com/photos/random_HTTP/1.1 Authorization: Client-ID abc123 ``` Here’s what an external credential that uses a custom header with an API key can look like. - The credential uses a custom authorization protocol. - It uses a `Load Stock Photos` principal. - It’s linked to a `Random Stock Photo` named credential, which can have its own custom header. - `AccessKey` is defined in the principal. ![Stock photo external credential](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/240_stock_photo_app_ext_cred_02.png) See [Use API Keys in Custom Headers with Named Credentials](https://help.salesforce.com/s/articleView?id=xcloud.nc_custom_headers_and_api_keys.htm&release=264.0.0&type=5 "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."). ## Custom Headers in Named Credentials Define custom headers at the level of a named credential if the headers are contextual to a single endpoint. An example of a header that works better on a named credential is a billing identifier. In all likelihood, this type of identifier has nothing to do with authentication or security, and it can be different for each endpoint. ``` GET https://example.com/method?abc=def HTTP/1.1 X-Billing-Code: costCenter123 ``` #### See Also - [Named Credentials](https://help.salesforce.com/s/articleView?id=xcloud.named_credentials_about.htm&release=264.0.0&type=5 "Intended to secure and simplify authenticated API callouts to external systems, a named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. To streamline your Apex code and simplify the setup of authenticated callouts, specify a named credential as the callout endpoint.") - [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.")