NamedCredential | Metadata API Developer Guide

All credentials stored within this entity are encrypted under a framework that is consistent with other encryption frameworks on the platform. Salesforce encrypts your credentials by auto-creating org-specific keys. Credentials encrypted using the previous encryption scheme have been migrated to the new framework.

Note

This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

NamedCredential components have the suffix .namedCredential and are stored in the namedCredentials folder.

Version

NamedCredential components are available in API version 33.0 and later.

Special Access Rules

As of Spring ’20 and later, only users with the View Setup and Configuration permission can access this type.

Fields

Field Name	Field Type	Description
awsAccessKey	string	First part of the access key used to sign programmatic requests to AWS. Use when AWS Signature Version 4 is your authentication protocol. This field is available in API version 46.0 and later.
awsAccessSecret	string	The second part of the access key used to sign programmatic requests to AWS. Use when AWS Signature Version 4 is your authentication protocol. This field is available in API version 46.0 and later.
awsRegion	string	Specifies which AWS Region the named credential accesses. This field is available in API version 46.0 and later.
awsService	string	Specifies which AWS resource the named credential accesses. This field is available in API version 46.0 and later.
allowMergeFieldsInBody	boolean	Specifies whether Apex code can use merge fields to populate the HTTP request body with org data when a callout is made. Corresponds to Allow Merge Fields in HTTP Body in the user interface. Defaults to `false`. This field is available in API version 41.0 and later.
allowMergeFieldsInHeader	boolean	Specifies whether Apex code can use merge fields to populate the HTTP header with org data when a callout is made. Corresponds to Allow Merge Fields in HTTP Header in the user interface. Defaults to `false`. This field is available in API version 41.0 and later.
authProvider	string	The authentication provider that the AuthProvider component represents.
authTokenEndpointUrl	string	The URL where JWTs are exchanged for access tokens. This field is available in API version 46.0 and later.
certificate	string	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.
endpoint	string	The URL or root URL of the callout endpoint. Corresponds to URL in the user interface.
generateAuthorizationHeader	boolean	Specifies whether Salesforce generates an authorization header and applies it to each callout that references the named credential. Corresponds to Generate Authorization Header in the user interface. Defaults to `true`. This field is available in API version 41.0 and later.
jwtAudience	string	External service or other allowed recipients for the JWT. Written as JSON, with a quoted string for a single audience and an array of quoted strings for multiple audiences. Single audience example: “aud1” Multiple audiences example: [“aud1”, “aud2”, “aud3”]
jwtFormulaSubject	string	Formula string calculating the JWT’s Subject. API names and constant strings, in single quotes, can be included. Allows a dynamic Subject unique per user requesting the token. For example, `'User='+$User.Id`. Use this field when principalType is set to `PerUser`. Corresponds to Per User Subject in the user interface. This field is available in API version 46.0 and later
jwtIssuer	string	Specify who issued the JWT using a case-sensitive string. This field is available in API version 46.0 and later.
jwtSigningCertificate	string	Certificate verifying the JWT’s authenticity to external sites. This field is available in API version 46.0 and later.
jwtTextSubject	string	Static text, without quotes, that specifies the JWT Subject. Use this field when principalType is set to `NamedUser`. Corresponds to Named Principal Subject in the user interface. This field is available in API version 46.0 and later
jwtValidityPeriodSeconds	string	Specify the number of seconds that the token is valid. This field is available in API version 46.0 and later.
label	string	A user-friendly name for the named credential that appears in the Salesforce user interface, such as in list views.
oauthRefreshToken	string	The OAuth refresh token. Used to obtain a new access token for an end user when a token expires.
oauthScope	string	Specifies the scope of permissions to request for the access token. Corresponds to Scope in the user interface.
oauthToken	string	The access token that’s issued by your authorization server.
outboundNetworkConnection	string	Specifies the outbound network connection that uses the named credential to send call outs to AWS. Available in API version 49.0 and later.
password	string	The password to be used by your org to access the external system. Ensure that the credentials have adequate privileges to access the external system. Depending on how you set up access, you might need to provide the administrator password.
principalType	`ExternalPrincipalType` (enumeration of type string)	Determines whether you're using one set or multiple sets of credentials to access the external system. Corresponds to Identity Type in the user interface. The valid values are: `Anonymous` `PerUser` `NamedUser`
protocol	`AuthenticationProtocol` (enumeration of type string)	The authentication protocol that’s required to access the external system. The valid values are: `AwsSig4` `Jwt` `JwtExchange` `NoAuthentication` `Oauth` `Password` For connections to Amazon Web Services using Signature Version 4, use `AwsSig4`. For connections using a direct token system, select `Jwt`. If using an intermediary authorization provider to process JWTs and return access tokens, use `JwtExchange`. For Simple URL data sources, select `NoAuthentication`. For cloud-based Files Connect external systems, select `Oauth`. For on-premises systems, select `Password`.
username	string	The username to be used by your org to access the external system. Ensure that the credentials have adequate privileges for performing callouts to the external system. Depending on how you set up access, you might need to provide the administrator username.

Declarative Metadata Sample Definition

The following is an example of a NamedCredential component.

1<?xml version="1.0" encoding="UTF-8"?>
2<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
3    <allowMergeFieldsInBody>false</allowMergeFieldsInBody>
4    <allowMergeFieldsInHeader>false</allowMergeFieldsInHeader>
5    <endpoint>https://my_endpoint.example.com</endpoint>
6    <generateAuthorizationHeader>true</generateAuthorizationHeader>
7    <label>My Named Credential</label>
8    <principalType>Anonymous</principalType>
9    <protocol>NoAuthentication</protocol>
10</NamedCredential>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.