--- schema_version: "1" id: f8b3ca7643444c72ea8b978a732273e5b164bfd26062ec4d5b9c9a151f1f6fba title: Named Credentials Schema collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/xcloud/264-0-0/nc_parts_of_nc.md canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.nc_parts_of_nc.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 5c67c3efee88363f63db4a5950173a9d252cfc6f0edee15df7dd067728f24890 description: Named credentials and external credentials simplify and enable greater reuse of setup for secure and authenticated callouts. products: - Security release: "264" --- # Named Credentials Schema Named credentials and external credentials simplify and enable greater reuse of setup for secure and authenticated callouts. ### Required Editions
Available in: both Salesforce Classic and Lightning Experience
Available in: all editions
## Parts of the Named Credential Schema Understand the different parts of the named credential schema. ![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. - A named credential specifies a callout endpoint and an HTTP transport protocol. - An external credential’s authentication protocol and user credentials authenticate the caller. More than one named credential can use the same external credential. - External credential principals map to permission sets to authorize users to make callouts. - User external credentials store encrypted tokens. - External auth identity providers obtain OAuth tokens for outbound callouts. ![Named credentials schema](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_named_credentials_chime_example_01b.png) ## Named Credentials A named credential is a logical entity that can be thought of as a named connection to an external system. With named credentials, there’s no need to embed a physical URL into Apex code and manage authentication tokens in unencrypted data stores. Instead, a variable in the code allows a Salesforce admin to provision the physical endpoint at deployment time and manage user credentials in the org’s encrypted credential store. The named credential URL is resolved at run time to the configured physical endpoint along with the credentials for the authorized user performing the callout. You can customize a named credential. For example, you can define HTTP headers with Salesforce formula functions to tailor header values to the calling user context or substitute formula function variables in the request body. There are different types of named credentials. Advanced use cases can benefit from storing custom parameters, which are also supported. A parameter is essentially a name-value pair to capture arbitrary metadata, and the parameter values are stored securely. A named credential can be one of these types. SecuredEndpoint The named credential includes an endpoint’s transport protocol as secured through transport layer security (TLS). This is the default named credential type. PrivateEndpoint The named credential sends traffic through a private connection, bypassing the public internet. Legacy A legacy named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. ## External Credentials Security policies often mandate that authentication details change on a rotating basis. An external credential encapsulates the details of how Salesforce authenticates to a remote system. By externalizing authentication information from the code, developers aren’t required to change these details to stay compliant with such policies. Hyperscale cloud infrastructure providers often host many different systems, and a single set of credentials can be used to access multiple named systems. A named credential holds a reference to an external credential, and multiple named credentials can benefit from sharing a single external credential. For example, a Salesforce integration can access the APIs for Google Drive and Google Calendar with the same credentials. Authentication protocols such as OAuth or AWS Signature v4 specify how to authenticate with an external system. For example, they can specify how access keys are exchanged or how to refresh expired access keys. The protocol specifies implementation details handled by the platform, such as how keys are exchanged and when they’re refreshed. Authentication parameters are captured as external credential name-value pairs. See the API documentation for authentication of protocol-specific parameters. ## Permission Sets The Salesforce platform supports the use of permission sets to control which users are authorized to make callouts. External credentials authenticate users, and permission sets authorize users. You link an external credential to permission sets or user profiles through external credential principals. At run time, the platform ensures that the user has the permission set before accessing the remote system. Development teams can choose to package permission sets representing access to a specific remote system, though admins retain the option to associate the external credential with other permission sets of their choosing. ![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 To apply credential permissions to the largest number of users, you can link a permission set to a principal and then add the permission set to a permission set group. ## User External Credentials Tokens for named credential callouts are encrypted and stored in a user external credential object. Any user performing an authenticated callout also 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. Though the runtime behavior of named credentials reads the tokens from the user external credential object, there’s no access to this object’s records from SOQL, Apex, or the APIs. The tokens can be deleted programmatically using a special method in Connect REST API. ## External Auth Identity Provider An external credential that uses OAuth 2.0 authentication can reference an external auth identity provider, which obtains the OAuth tokens necessary for outbound callouts to external systems. To customize requests to the identity provider’s token endpoint and specify the tenant to access in multi-tenant systems, you can attach account IDs or tenant IDs as custom request parameters. Unlike Auth. Provider, which can also link to an external credential, you can create external auth identity providers via Connect REST API or Apex. Also, you can include them in second-generation managed packages (managed 2GP) and unlocked packages for distribution across many orgs or across one org’s development, test, and production environments. #### 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.")