--- schema_version: "1" id: 0b5273a60916e27151e506cf82fbaed9797cc39450ae9036648fe0c645dc86f5 title: Define a Legacy Named Credential collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/xcloud/264-0-0/named_credentials_define.md canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.named_credentials_define.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 572731c3499722d3b49a73c661297aebef2d551fcdf0b82503deabc88ff6cd72 description: Create a legacy named credential to specify the URL of a callout endpoint and its required authentication parameters in one definition. You can then specify the legacy named credential as a callout endpoint to let Salesforce handle all authentication. You can also skip remote site settings, which are otherwise required for callouts to external sites, for the site defined in the legacy named credential. products: - Security release: "264" --- # Define a Legacy Named Credential Create a legacy named credential to specify the URL of a callout endpoint and its required authentication parameters in one definition. You can then specify the legacy named credential as a callout endpoint to let Salesforce handle all authentication. You can also skip remote site settings, which are otherwise required for callouts to external sites, for the site defined in the legacy named credential. ### Required Editions
Available in: both Salesforce Classic and Lightning Experience
Available in: All Editions
User Permissions Needed
To view legacy named credentials: View Setup and Configuration
To create, edit, or delete legacy named credentials: Manage Named Credentials or Customize Applications
![Important](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-security-264-0-0-production-enus/8cecd769-ab2d-4e07-addf-c4f2927925e1/images/icon_important.png) Important In Winter ’23, Salesforce introduced an improved named credential that’s extensible, customizable, and more secure. We strongly recommend that you use this preferred credential instead of legacy named credentials, which are no longer updated or enhanced. For information on extensible, customizable named credentials, see [Named Credentials Schema](https://help.salesforce.com/s/articleView?id=xcloud.nc_parts_of_nc.htm&release=264.0.0&type=5 "Named credentials and external credentials simplify and enable greater reuse of setup for secure and authenticated callouts."). Legacy named credentials are supported in these types of callout definitions: - Apex callouts - External data sources of these types: - Salesforce Connect: OData 2.0 - Salesforce Connect: OData 4.0 - Salesforce Connect: Custom (developed with the Apex Connector Framework) - Salesforce Connect: Amazon DynamoDB - External Services To set up a legacy named credential: 1. From [Setup](https://help.salesforce.com/s/articleView?id=xcloud.basics_nav_setup.htm&type=5&language=en_US), use the Quick Find box to find and select **Named Credentials**. 2. To create a legacy named credential, click **New Legacy** from the dropdown menu. To edit an existing legacy credential, click its link and click **Edit**. 3. Enter information in the fields.
Field Description
Label

A user-friendly name for the legacy named credential that’s displayed in the Salesforce user interface, such as in list views.

If you set Identity Type to Per User, this label appears when your users view or edit their authentication settings for external systems.

Name

A unique identifier that’s used to refer to this legacy named credential from callout definitions and through the API.

The name can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
URL

The URL or root URL of the callout endpoint. Must begin with http:// or https://. Can include a path but not a query string. Examples:

  • http://my_endpoint.example.com
  • https://my_endpoint.example.com/secure/payroll

You can, however, append a query string and a specific path in the callout definition’s reference to the legacy named credential. For example, an Apex callout could reference the legacy named credential “My_Payroll_System” as follows.

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:My_Payroll_System/paystubs?format=json');
Certificate

If you specify a certificate, your Salesforce org supplies it when establishing each two-way SSL connection with the external system. The certificate is used for digital signatures, which verify that requests are coming from your Salesforce org.

This certificate is for the callout endpoint URL. If you plan to use the JWT or JWT Token Exchange authentication protocol, enter the token endpoint URL certificate in the JWT Signing Certificate field. The JWT Signing Certificate field is displayed when you select JWT or JWT Token Exchange for the Authentication Protocol field, as described in a later step.
Identity Type

Determines whether you're using one set or multiple sets of credentials to access the external system.

  • Anonymous: No identity and therefore no authentication.
  • Per User: Use separate credentials for each user who accesses the external system via callouts. Select this option if the external system restricts access on a per-user basis.

    After you grant user access through permission sets or profiles in Salesforce, users can manage their own authentication settings for external systems in their personal settings. If you’re using JWT or JWT Token Exchange, the per-user credentials are handled for them.

  • Named Principal: Use the same set of credentials for all users who access the external system from your org. Select this option if you designate one user account on the external system for all your Salesforce org users.
4. Select the authentication protocol. - If you select **Password Authentication**, enter the username and password for accessing the external system. - If you select **OAuth 2.0**, complete the following fields.
Field Description
Authentication Provider Choose the provider. See Authentication Provider SSO.
Scope

Specifies the scope of permissions to request for the access token. Your authentication provider determines the allowed values. See Use the Scope Parameter.

  • The value that you enter replaces the Default Scopes value that’s defined in the specified authentication provider.
  • Whether scopes are defined can affect whether each OAuth flow prompts the user with a consent screen.
  • We recommend that you request a refresh token or offline access. Otherwise, when the token expires, you lose access to the external system.
Start Authentication Flow on Save

To authenticate to the external system and obtain an OAuth token, select this checkbox. This authentication process is called an OAuth flow.

When you click Save, the external system prompts you to log in. After successful login, the external system grants you an OAuth token for accessing its data from this org.

Redo the OAuth flow when you need a new token—for example, if the token expires—or if you edit the Scope or Authentication Provider fields. When the token expires, the external system returns a 401 HTTP error status.
- If you select **JWT** or **JWT Token Exchange**, complete the following fields. | Field | Description | | --- | --- | | Issuer | Specify who issued the JWT using a case-sensitive string. | | Scope | JWT Token Exchange only. Determines the permissions associated with the tokens that you’re requesting. | | Token Endpoint URL | JWT Token Exchange only. The URL of the authorization provider. JSON Web Token requests are sent to the provider in exchange for access tokens. | | Per User Subject | Per User identity type only. Formula string calculating the JWT’s subject. Include API names and constant strings in quotes. Allows a dynamic subject unique per user requesting the token. For example, 'User='+$User.Id. | | Named Principal Subject | Named Principal identity type only. Enter static text, without quotes, that specifies the JWT subject. | | Audiences | External service or other allowed recipients for the JWT. Store each audience as a case-sensitive string on a new line. | | Token Valid for | The length of time that the token is valid to authenticate the user into the external system. | | JWT Signing Certificate | Certificate verifying the JWT’s authenticity to external systems. | - If you select **AWS Signature Version 4**, complete the following fields. | Field | Description | | --- | --- | | AWS Access Key ID | First part of the access key used to sign programmatic requests to AWS. | | AWS Secret Access Key | Second part of the access key used to sign programmatic requests to AWS. | | AWS Region | The AWS region name for the legacy named credential’s endpoint. For example, us-east-1. | | AWS Service | The AWS utility to access. | 5. If you want to use custom headers or bodies in the callouts, enable the relevant options.
Field Description
Generate Authorization Header

By default, Salesforce generates an authorization header and applies it to each callout that references the legacy named credential.

Deselect this option only if one of the following statements applies.

  • The remote endpoint doesn’t support authorization headers.
  • The authorization headers are provided by other means. For example, in Apex callouts, the developer can have the code construct a custom authorization header for each callout.

This option is required if you reference the legacy named credential from an external data source.

Allow Merge Fields in HTTP Header

Allow Merge Fields in HTTP Body

In each Apex callout, the code specifies how the HTTP header and request body are constructed. For example, the Apex code can set the value of a cookie in an authorization header.

These options enable the Apex code to use merge fields to populate the HTTP header and request body with org data when the callout is made.

These options aren’t available if you reference the legacy named credential from an external data source.
To reference a legacy named credential from a callout definition, use the legacy named credential URL. A legacy named credential URL contains the scheme `callout:`, the name of the legacy named credential, and an optional path. For example: `callout:`My\_Named\_Credential`/`some\_path. You can append a query string to a legacy named credential URL. Use a question mark (?) as the separator between the legacy named credential URL and the query string. For example: `callout:`My\_Named\_Credential`/`some\_path`?format=json`. #### See Also - [Understand Legacy Named Credentials](https://help.salesforce.com/s/articleView?id=xcloud.named_credentials_legacy_about.htm&release=264.0.0&type=5 "A legacy named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. Legacy named credentials are deprecated and are unsupported in future releases.") - [Authentication Protocols for Named Credentials](https://help.salesforce.com/s/articleView?id=xcloud.nc_auth_protocols.htm&release=264.0.0&type=5 "Your connections between Salesforce and external systems use an authentication protocol to confirm secure communication between the two systems. Choose the authentication protocol that matches the configuration of the external system that you connect to. When you do, keep the strengths and considerations of each authentication protocol in mind.") - [Grant Access to Authentication Settings for Legacy Named Credentials](https://help.salesforce.com/s/articleView?id=xcloud.named_credentials_permsets_profiles.htm&release=264.0.0&type=5 "For legacy named credentials that use per-user authentication, grant access to users through permission sets and profiles. Doing so lets users set up and manage their own authentication settings for accessing the external system.") - [_Apex Developer Guide_: Invoking Callouts Using Apex](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts.htm) - [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.")