Named Credential
A Named Credential is a Salesforce configuration that stores the endpoint URL and authentication details for an external service in one named, secured construct.
Definition
A Named Credential is a Salesforce configuration that stores the endpoint URL and authentication details for an external service in one named, secured construct. Apex callouts, Flow HTTP actions, and Salesforce Connect external data sources reference the Named Credential by name instead of hardcoding URLs and credentials. This keeps secrets out of code, simplifies environment-specific URL handling, and centralizes credential rotation across every integration that uses the service.
Named Credentials sit at the intersection of integration and security. They support multiple authentication protocols (Password, OAuth 2.0, JWT bearer, AWS Signature Version 4, mTLS, and custom headers), handle the authentication handshake automatically, and refresh OAuth tokens as needed without the caller writing any token-management code. The modern Named Credential model (introduced in 2022) separates the endpoint configuration (External Credential, Permission Set Mapping) from the URL routing (Named Credential), which makes credential reuse across multiple endpoints clean and audit-friendly.
How Named Credentials secure external system integrations
Legacy versus modern Named Credential model
The original Named Credential model (still supported) bundled URL and authentication into one object. The modern model (called Named Credential 2.0 or the External Credential model, introduced in 2022) splits them: External Credential holds the authentication configuration, Permission Set Mapping ties principals to that credential, and the Named Credential routes URLs through the External Credential. The modern model handles per-user credentials, principal-named credentials, and complex authentication patterns more cleanly. New integrations should use the modern model; legacy ones still work but are scheduled for eventual replacement.
Authentication protocols supported
Named Credentials support the protocols every common integration needs: Password Authentication for legacy basic-auth APIs, OAuth 2.0 with the standard grant types (authorization code, client credentials, JWT bearer), AWS Signature Version 4 for AWS API calls, mutual TLS with client certificates, and Custom for header-based or query-string-based auth. The platform handles the handshake automatically: Apex calls HttpRequest, the platform injects the right credentials before sending the request, and the response comes back with no token-management code in user-land.
Apex callout syntax and the callout: URL prefix
Apex makes callouts to Named Credentials by prefixing the URL with callout::My_Credential_Name. The platform resolves the URL to the configured endpoint, injects authentication headers, and sends the request: req.setEndpoint(''callout:Salesforce_Org/services/data/v60.0/query?q=SELECT+Name+FROM+Account''). Path segments after the credential name append to the configured endpoint. This pattern keeps credential management out of Apex and lets the same code work across sandbox and production by changing only the Named Credential configuration.
Per-user versus org-wide credentials
Named Credentials support two principal modes. Named Principal uses one set of credentials shared by all users (typical for service accounts and system-to-system integrations). Per User uses each user''s own credentials (typical for integrations that need to act as the user, like a Slack lookup that returns each user''s Slack username). Per User credentials require each user to authorize the integration in their personal settings; admin authorization does not work across user boundaries. The modern External Credential model handles this distinction cleanly through Permission Set Mapping.
OAuth token management
For OAuth-based Named Credentials, the platform manages the token lifecycle automatically. Initial authorization establishes the refresh token. Each callout uses a fresh access token, refreshing through the OAuth refresh endpoint when the current token expires. Failed refreshes propagate as callout failures, which the caller can catch and handle. The user (or admin for Named Principal credentials) sees an authorization prompt on first use; subsequent calls run silently as long as the refresh token remains valid.
Headers, parameters, and custom HTTP behavior
Named Credentials let you specify custom request headers and parameters that should always accompany callouts. Common patterns: a fixed API version header (X-API-Version: 2024-01), a tenant identifier (X-Tenant-ID: acme), a feature flag (X-Beta-Flag: enabled). These travel with every callout to that credential without the Apex caller having to remember them. The platform also supports per-callout overrides via HttpRequest.setHeader, which take precedence over Named Credential defaults.
Migration, deployment, and audit
Named Credentials deploy through change sets and metadata API. The Named Credential definition deploys as metadata. The External Credential definition deploys separately. Secrets (Consumer Secrets, certificates, passwords) do NOT deploy with the metadata; each environment needs the secrets configured manually after deployment, usually through the post-deployment runbook. Setup Audit Trail logs all Named Credential changes, which is the standard audit evidence for SOC 2 and similar compliance reviews of credential-management practices.
How to create a Named Credential
Creating a Named Credential is the cleanest way to integrate Salesforce with an external service. Pick the authentication protocol, configure the endpoint, set the principal mode, and reference the credential from Apex or Flow. The hard part is matching the credential configuration to the external service''s expected authentication, which usually requires reading the target API''s docs carefully.
- Identify the external service and authentication scheme
Read the target API documentation. Note the authentication protocol (OAuth, basic auth, custom headers, certificates), the endpoint URL, any required headers or query parameters, and whether the integration needs to act as a service account or as the calling user.
- Create the External Credential (modern model)
Setup > Named Credentials > External Credentials tab > New. Pick the authentication protocol. Configure the OAuth client ID/secret, certificate, AWS key, or basic auth credentials. Save and define the Permission Set Mapping that grants access to the right user populations.
- Create the Named Credential
Setup > Named Credentials > Named Credentials tab > New. Enter the URL of the external service. Pick the External Credential you just created. Configure any custom headers or parameters that should accompany every callout.
- Set the principal mode (Named or Per User)
Named Principal for service-account integrations (the typical default). Per User for integrations that need to act as the calling user. Per User requires each user to authorize the integration through their personal settings before they can call it.
- Authorize the credential (OAuth flows)
For OAuth-based credentials, click Authorize from the External Credential detail page. The platform redirects to the external system''s authorization endpoint. Approve and return to Salesforce. The refresh token persists and future callouts run silently.
- Reference from Apex with the callout prefix
req.setEndpoint(''callout:My_External_Service/api/v1/widgets''). The platform resolves to the configured URL and injects authentication. No token management or URL manipulation in Apex.
- Reference from Flow with the HTTP Callout action
In a Flow, add the HTTP Callout action. Pick the Named Credential. The Flow handles the request and response without code. Use this for declarative integrations that do not warrant Apex.
- Deploy and test in each environment
Deploy via change set or metadata API. Configure secrets per environment because they do not travel with metadata. Run a test callout from Anonymous Apex or Flow Debug to verify the credential resolves correctly before production traffic.
Password, OAuth 2.0, JWT Bearer, AWS Signature Version 4, mTLS, or Custom Header. Drives every other config choice.
Named for service accounts shared across users. Per User for integrations that act as the calling user with their own credentials.
Headers and query parameters that automatically accompany every callout to this credential. Useful for version pinning, tenant identifiers, and feature flags.
- Secrets do not deploy with Named Credential metadata. Each environment requires manual configuration of OAuth secrets, certificates, and passwords after deployment.
- Per User principal credentials require each user to authorize the integration through their personal settings. Admin pre-authorization does not work across user boundaries.
- Callouts inside trigger contexts must be marked future or queueable because triggers cannot make synchronous callouts. The platform throws CalloutException otherwise.
- Failed OAuth refreshes propagate as callout failures. Build retry logic with exponential backoff in Apex; the platform does not automatically re-authorize when refresh tokens expire.
- The legacy Named Credential model is still supported but new integrations should use the External Credential model. Salesforce intends to migrate legacy credentials over time, so investing in the old model creates technical debt.
Trust & references
Cross-checked against the following references.
- Named Credentials OverviewSalesforce Help
- Define a Named CredentialSalesforce Help
- External CredentialsSalesforce Help
Straight from the source - Salesforce's reference material on Named Credential.
- Named Credentials DocumentationSalesforce Help
- Create a Named CredentialSalesforce Help
- Apex Callouts with Named CredentialsSalesforce Developer
Hands-on resources to go deeper on Named Credential.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is required before deploying Named Credential-related code to production?
Q2. What is a Governor Limit in the context of Named Credential?
Q3. What skill set is typically needed to work with Named Credential?
Discussion
Loading discussion…