Named Credentials and External Services: Secure API Integration

The Problem Named Credentials Solve

Without Named Credentials, Salesforce integrations typically embed API keys, usernames, and passwords in Apex code or Custom Settings. This creates three problems: secrets are visible to anyone who can view Apex code, rotating a credential requires a code deployment, and security reviews cannot easily audit what external systems are being called with what credentials.

Named Credentials centralise external endpoint configuration and authentication in Setup — a governed, auditable location that only system admins control. Apex code references the Named Credential by name, never seeing the actual credentials.

Named Credentials: Architecture

A Named Credential stores: the endpoint URL, the authentication protocol (Basic, OAuth 2.0, JWT, Custom Header, AWS Signature), and optionally a certificate for mutual TLS. There are two types of authentication scope:

• Named Principal (org-wide): All callouts using this credential use the same authentication — typically a service account. The credential is stored once and shared across all transactions.
• Per-User Principal: Each Salesforce user authenticates individually against the external system via their own OAuth flow. The credential stores the per-user token, refreshes it automatically, and uses it when that user's Apex makes a callout. Ideal for integrations that require user-level audit trails on the external system.

// Apex callout using Named Credential
// No credentials in code — Salesforce injects auth headers automatically
HttpRequest req = new HttpRequest();
req.setEndpoint('callout:My_ERP_API/orders?status=pending');
req.setMethod('GET');
req.setHeader('Content-Type', 'application/json');

HttpResponse res = new Http().send(req);
if (res.getStatusCode() == 200) {
  List<Object> orders = (List<Object>) JSON.deserializeUntyped(res.getBody());
}

// 'callout:My_ERP_API' is the Named Credential API name
// The base URL and auth headers are merged automatically by Salesforce
// The endpoint becomes: https://erp.mycompany.com/api/orders?status=pending

External Services: OpenAPI to Salesforce Actions

External Services (formerly "Salesforce External Services") allows architects to import an OpenAPI 3.0 (Swagger) specification of a REST API and have Salesforce automatically generate invocable actions, Flow actions, and Apex types from the spec. This means you can call an external REST API from a Flow without writing any Apex code.

The workflow:

1. Create a Named Credential for the external endpoint.
2. Import the OpenAPI 3.0 spec from a URL or file upload in Setup > Integrations > External Services.
3. Salesforce parses the spec and creates invocable actions for each endpoint.
4. Use the generated actions in Flow, Apex, or Einstein Next Best Action.

// After External Services import, the API is callable from Flow:
// Flow Element: "Action" -> "External Services"
// Shows: GetOrders, CreateOrder, UpdateOrderStatus, etc.
// Each action maps to one API endpoint from the OpenAPI spec

// Also callable from Apex via generated type-safe classes:
ExternalService.ERPOrders_GetOrdersInput input =
  new ExternalService.ERPOrders_GetOrdersInput();
input.status = 'pending';

ExternalService.ERPOrders_GetOrdersOutput output =
  ExternalService.ERPOrders.getOrders(input);

for (ExternalService.ERPOrders_Order order : output.orders) {
  System.debug(order.id + ': ' + order.status);
}

Security Considerations

Named Credentials respect Salesforce data security in the Named Principal model — all callouts use the same service account credentials regardless of the Salesforce user. This means external system audit logs show the service account, not the individual user. If individual user audit trails are required on the external system, use Per-User Principal instead.

OAuth 2.0 Named Credentials store the refresh token encrypted in Salesforce. The encryption uses Salesforce's key management infrastructure. For orgs with Salesforce Shield, you can use tenant secrets to add an additional encryption layer.

External Credentials vs Named Credentials (Winter 2024+)

Salesforce introduced External Credentials as a separate concept in Winter 2024 to decouple the authentication configuration from the endpoint configuration. External Credentials define the auth (OAuth app, JWT settings, API key). Named Credentials (now called Legacy Named Credentials vs new Named Credentials) reference an External Credential for auth and define the endpoint URL separately. This separation allows the same auth configuration to be reused across multiple endpoints.