Named Credential
A Named Credential in Salesforce securely stores the URL and authentication settings for an external service endpoint.
Definition
A Named Credential in Salesforce securely stores the URL and authentication settings for an external service endpoint. By referencing a Named Credential in Apex callouts or External Services, developers avoid hardcoding URLs and credentials in code, improving security and making it easy to update endpoints without code changes.
In plain English
“Here's a simple way to think about it: Named Credentials are how Apex authenticates to external systems without hardcoded secrets. Code references the credential by name; the platform substitutes URL, OAuth, certificates. The code never sees a secret.”
Worked example
A developer at LogiTrack creates a Named Credential called "ShippingAPI" that stores the base URL and OAuth credentials for their shipping provider's API. In the Apex callout code, she simply references callout:ShippingAPI/v2/track instead of hardcoding the URL and token. When the shipping provider rotates their API keys, the admin updates the Named Credential without touching any code.
Why Named Credentials are how Apex authenticates to external systems without hardcoded secrets
Apex code can call external HTTP endpoints, but doing so requires credentials - a URL, an auth method, sometimes a token or certificate. Named Credential is the platform feature that lets you store all of those securely outside the code. The Apex callout references the credential by name (callout:MyEndpoint) and the platform substitutes the URL, handles the OAuth flow, and presents the credentials to the external service. The code itself never sees a secret.
The reason this matters past convenience is security and maintainability. Hardcoded credentials in Apex are visible to anyone with read access to the class; rotating them requires a redeploy; revoking access for one integration forces edits across many code paths. Named Credentials centralize the credential management, support modern auth flows (OAuth 2.0, JWT bearer), and let the integration team rotate credentials without involving developers. Always default to Named Credentials for any Apex callout.
How to set up Named Credential
Named Credentials wrap an external endpoint URL plus its authentication into a single named reference your Apex code can call without ever seeing the actual auth tokens. Modern Named Credentials separate the Endpoint (Named Credential) from the Auth (External Credential) — older blogs may show the legacy combined form, which is being retired.
- Open Setup → Named Credentials
Setup gear → Quick Find: Named Credentials. The page has two tabs: Named Credentials and External Credentials.
- Open the External Credentials tab → New
External Credentials hold the auth — pick a protocol (OAuth 2.0 / AWS Signature v4 / Custom / Mutual TLS / Basic).
- Configure the Auth Protocol
OAuth 2.0: provider URL, client ID/secret, scopes. AWS: access key, secret. Custom: header name + token.
- Add a Principal under the External Credential
Principals say WHO authenticates. Named Principal (one identity for all users) or Per-User Principal (each user authenticates independently).
- Open the Named Credentials tab → New
The endpoint side. Set Label, Name, URL (the base URL of the API), and link to your External Credential.
- Save
Named Credential is ready to call.
- Reference from Apex
HttpRequest req = new HttpRequest(); req.setEndpoint('callout:MyNC/path/to/resource'); req.setMethod('GET'); — Salesforce auto-attaches the auth from the External Credential.
OAuth 2.0 / AWS Sig v4 / Custom (header) / Mutual TLS / Basic. OAuth 2.0 is the most common.
Named Principal (shared identity) or Per-User (each user logs in).
When ticked, restricts which Apex namespaces can use this credential. Useful for managed packages.
If Salesforce Private Connect is enabled, route through a private network instead of the public internet.
When ticked, Salesforce auto-builds the Authorization header. Untick if your endpoint uses query params or a custom header.
- Modern Named Credentials separated External Credential (auth) from Named Credential (endpoint). Pre-2023 docs show a combined form — that legacy mode still works but new ones should use the split structure.
- Per-User principals require each user to do a one-time auth dance with the provider. For service-account integrations, use Named Principal — much easier.
- OAuth 2.0 callbacks need the Salesforce callback URL on the provider side. Same gotcha as Auth. Providers — provider-side config is half the work.
How organizations use Named Credential
Migrated 15 hardcoded API endpoints to Named Credentials; rotation became a config change instead of a deploy.
Compliance team requires Named Credentials for any production Apex callout; secrets-in-code is a security finding.
Trust & references
Straight from the source - Salesforce's reference material on Named Credential.
- Named CredentialsSalesforce Help
- Create Named Credentials and External CredentialsSalesforce Help
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…