Named Credentials in Sandboxes: The DevOps Lifecycle Guide

You refresh a Full or Developer Pro sandbox, log in with high expectations, and the first outbound integration you touch throws an authentication failure. The Named Credentials did not come across. It is one of the most persistent complaints I hear from Salesforce architects and developers.

Why Named Credentials don't copy

A sandbox refresh performs a deep copy of your production metadata, but Named Credentials are excluded on purpose, for security and compliance reasons.

A Named Credential is a bridge between your org and a third-party service that may hold sensitive data. If the stored credentials came across (OAuth tokens, API keys, password-based secrets), developers working in a lower-trust environment could invoke production API endpoints with production-grade authorization. Leaving them behind forces a manual setup or a scripted redeployment, which is also the moment you point your sandbox integrations at development or staging endpoints.

The immutable infrastructure approach

Plenty of teams file Named Credentials under "manual configuration" that an admin sorts out after the refresh. That is how technical debt accumulates. If environment setup costs four hours of clicking after every refresh, your pipeline is not continuous in any useful sense.

Treat them as infrastructure as code instead. Plaintext secrets never belong in your Git repository, but the metadata definition of the Named Credential does.

Step 1: extract the metadata with SFDX

Pull the existing Named Credential definitions from your source of truth, or from a correctly configured scratch org, using Salesforce CLI:

sfdx project retrieve start -m NamedCredential:MyApiIntegration

That gives you a .namedCredential-meta.xml file holding the definition: endpoint, auth protocol, and so on. The sensitive secrets are soql-not-in-not-equal-exclusion/" class="auto-link">not in it.

Automating the post-refresh workflow

The secret components cannot be deployed, so automate the plumbing around them.

Using External Credential providers

On the modern External Credentials architecture the path is cleaner. Bundle the External Credential and the Named Credential structure into your deployment package, and leave only the final authentication parameter, the API key or OAuth secret, for a developer or a secure vault to inject.

The deployment scripting pattern

With a high volume of integrations, put a custom post-refresh script in your CI/CD runner: GitHub Actions, Jenkins, GitLab CI, whatever you run. The sfdx force:source:deploy command pushes the structural metadata, then a simple Apex script updates the remaining parameters.

An example post-refresh.apex template:

// This script assumes the Named Credential structural metadata is already present
// Update the Auth parameters via Tooling API or custom settings approach
HttpRequest req = new HttpRequest();
req.setEndpoint('callout:MyNamedCredential');
// In a sandbox, we inject the staging key into a custom metadata record
// or a secure Protected Custom Setting to be used by an auth provider
System.debug('Named Credential ready for staging secret injection.');

Managing secrets safely: never commit them to Git

The tempting shortcut is storing raw credentials in Custom Metadata Types (CMDT) or static resources. Do not do this.

A CMDT that stores a password gets retrieved by your CI/CD tool and pushed to your Git repo, and now your production secrets are readable by anyone with access to that repository.

The strategy I recommend

1. Commit the structure, meaning the NamedCredential and ExternalCredential XML files.
2. Keep the secrets in a secret manager such as AWS Secrets Manager, HashiCorp Vault, or GitHub Secrets.
3. Have a small automation utility fetch the secret from your vault and use a NamedCredential service-level Apex call to populate the missing bits during the sandbox warm-up phase.