Package Named Credentials

A named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. Using named credentials abstracts away the details of authentication protocols like OAuth and simplifies code for Apex developers.

To create a named credential that matches the requirements of your authentication system, see Create and Edit an External Credential and Create and Edit a Named Credential. After you create a named credential, refer to these steps to package it, distribute it across your orgs, and populate access tokens.

This guide assumes that your development environment is configured to use second-generation managed packaging (managed 2GP). For more information, see Before You Create Second-Generation Managed Packages.

After your development environment is configured, retrieve the metadata for the named credential from your source org and package it to distribute it across orgs. A managed 2GP package can only be created through the Salesforce DX command-line interface (SFDX CLI).

To get started, follow the steps in Workflow for Second-Generation Managed Packages. Include these components in the package that you create.

External credential certificates and access tokens aren’t packageable. For more information, see the Populate External Credential Principals section.

To deploy your named credential to the target org, install the package that you created.

To use a URL to install your package, follow the steps in Use a URL to Install a Second-Generation Managed Package. For more information about non-default installations, pre-installation steps, and post-installation steps, see Install a Package.

Or to install the package using the CLI, see Use the CLI to Install a Second-Generation Managed Package.

You can view the components that the package installed from the Installed Packages page in Salesforce Setup. For more information, see View Installed Package Details.

  • When you package the permission set that grants access to the external credential’s principal, the package also includes that permission set’s setup entity access settings. When the package is installed, these settings are created in the target org.
  • Named credentials aren’t automatically added to packages. If you package an external data source or Apex code that specifies a named credential as a callout endpoint, add the named credential to the package. Alternatively, make sure that the subscriber org has a valid named credential with the same name.
    • For managed packages, the subscriber must add the package’s namespace to a named credential’s list of allowed namespaces to enable callouts. This action isn’t necessary if the named credential is installed as part of the same package.
    • If you have multiple orgs, you can create a named credential with the same name but with a different endpoint URL in each org. You can then package and deploy—on all the orgs—one callout definition that references the shared name of those named credentials. For example, the named credential in each org can have a different endpoint URL to accommodate differences in development and production environments. If an Apex callout specifies the shared name of those named credentials, the Apex class that defines the callout can be packaged and deployed on all those orgs without programmatically checking the environment.