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.