NamedCredential Metadata Type and Endpoint Guide

Overview#

The NamedCredential metadata type (namedCredentials/<Name>.namedCredential-meta.xml) defines the URL endpoint, callout options, custom HTTP headers, and authentication binding for outbound Apex HttpRequest, External Services, and Flow HTTP Callouts. When your code invokes req.setEndpoint('callout:Stripe_Gateway/v1/charges'), Salesforce resolves the Stripe_Gateway NamedCredential metadata, verifies the running user’s permission set access, signs or injects the authentication header, and dispatches the callout.

Since API version 56.0, Salesforce’s NamedCredential schema supports two architectures:

• Modern Extensible (<namedCredentialType>SecuredEndpoint</namedCredentialType>): Stores the endpoint URL, linked ExternalCredential, allowed managed package namespaces, and custom HTTP headers inside a flexible <namedCredentialParameters> array. Always use SecuredEndpoint for new integrations.
• Legacy (<namedCredentialType>Legacy</namedCredentialType>): Uses top-level <endpoint>, <protocol>, and <principalType> tags. Retained only for backward compatibility.

As shown in the diagram above, a modern SecuredEndpoint NamedCredential delegates all endpoint and header settings to typed <namedCredentialParameters> items and links directly to an ExternalCredential.

Prerequisites#

• Permissions: “Customize Application” and “View Setup and Configuration” permissions.
• External Credential Dependency: The ExternalCredential referenced in namedCredentialParameters must exist in the target org or be deployed in the same manifest.
• API Version: Introduced in API version 33.0; extensible SecuredEndpoint introduced in API version 56.0. Verified against API version 68.0 (Winter ’27).

Modern NamedCredentialParameter Types (API v56.0+)#

When <namedCredentialType>SecuredEndpoint</namedCredentialType> is set, configure the credential using <namedCredentialParameters> entries:

Querying NamedCredential via SOQL#

The NamedCredential object is available in standard SOQL and Tooling API.

1. Audit All Named Credentials in the Org (Standard SOQL)#

SELECT Id, DeveloperName, MasterLabel, Endpoint,
       PrincipalType, CalloutOptionsGenerateAuthorizationHeader,
       CalloutOptionsAllowMergeFieldsInHeader, LastModifiedDate
FROM NamedCredential
ORDER BY DeveloperName ASC

2. Inspect Extensible NamedCredentialParameter Configurations (Tooling API)#

Run with sf data query --use-tooling-api to inspect URLs, linked External Credentials, and custom headers on modern SecuredEndpoint credentials:

SELECT NamedCredential.DeveloperName, ParameterName, ParameterType,
       ParameterValue, ExternalCredential.DeveloperName, Certificate.DeveloperName
FROM NamedCredentialParameter
ORDER BY NamedCredential.DeveloperName ASC, SequenceNumber ASC

Example#

The following Stripe_Payment_Gateway.namedCredential-meta.xml defines a modern SecuredEndpoint Named Credential with calloutStatus enabled, linked to the Stripe_Auth External Credential, a mutual TLS client certificate, and a runtime custom header that passes the Salesforce Organization ID.

<?xml version="1.0" encoding="UTF-8"?>
<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
    <allowMergeFieldsInBody>false</allowMergeFieldsInBody>
    <allowMergeFieldsInHeader>false</allowMergeFieldsInHeader>
    <calloutStatus>Enabled</calloutStatus>
    <description>Production Stripe API v1 endpoint with mTLS and Org ID tracing header.</description>
    <generateAuthorizationHeader>true</generateAuthorizationHeader>
    <label>Stripe Payment Gateway</label>
    <namedCredentialParameters>
        <parameterName>Url</parameterName>
        <parameterType>Url</parameterType>
        <parameterValue>https://api.stripe.com</parameterValue>
    </namedCredentialParameters>
    <namedCredentialParameters>
        <externalCredential>Stripe_Auth</externalCredential>
        <parameterName>ExternalCredential</parameterName>
        <parameterType>ExternalCredential</parameterType>
    </namedCredentialParameters>
    <namedCredentialParameters>
        <parameterName>X-Salesforce-Org-Id</parameterName>
        <parameterType>CustomHeader</parameterType>
        <parameterValue>&apos;OrgId=&apos; &amp; $Organization.Id</parameterValue>
        <sequenceNumber>1</sequenceNumber>
    </namedCredentialParameters>
    <namedCredentialType>SecuredEndpoint</namedCredentialType>
</NamedCredential>

Deploy the NamedCredential and its companion ExternalCredential together:

sf project deploy start \
  --metadata ExternalCredential:Stripe_Auth NamedCredential:Stripe_Payment_Gateway \
  --target-org UATSandbox

Limits and Gotchas#

• Never Mix Legacy and SecuredEndpoint Tags: Including legacy tags (<endpoint>, <principalType>, <protocol>) alongside <namedCredentialType>SecuredEndpoint</namedCredentialType> causes a Metadata API deployment validation error.
• No Remote Site Setting Required: Endpoints defined in a NamedCredential automatically bypass RemoteSiteSetting checks; you do not need to deploy a duplicate RemoteSiteSetting for the same domain.
• URL Path Preservation: Do not include a trailing slash (/) at the end of the Url parameterValue (https://api.stripe.com) if your Apex callout path begins with a leading slash (callout:Stripe_Payment_Gateway/v1/charges), or the resolved URL will contain a double slash (//v1/charges).

Related Official Documentation#

• NamedCredential Metadata API Reference: Complete XML specification for NamedCredential and NamedCredentialParameter.
• Named Credentials and Secure Callout Architecture: End-to-end Apex callout implementation guide.

Frequently asked questions

Why are endpoint, principalType, and protocol marked deprecated in NamedCredential XML?

Starting in API version 56.0 (Winter '23), Salesforce introduced extensible Named Credentials (namedCredentialType = SecuredEndpoint). Endpoint URLs, ExternalCredential links, and custom headers now live inside namedCredentialParameters instead of top-level legacy fields.

How do I change a NamedCredential endpoint URL between Sandbox and Production in CI/CD?

Use string replacement or SFDX environment variables on the Url parameterValue inside the .namedCredential-meta.xml file during your CI/CD deployment pipeline, or switch calloutStatus between Enabled and Disabled.

What does calloutStatus on NamedCredential do?

Introduced in API version 59.0, calloutStatus lets you toggle a NamedCredential between Enabled and Disabled via Metadata API—ideal for immediately halting outbound callouts in a sandbox after a refresh.

How do I query NamedCredential records and their endpoints using SOQL?

Query the NamedCredential standard object in SOQL or Tooling API: SELECT Id, DeveloperName, MasterLabel, Endpoint, PrincipalType FROM NamedCredential, or query NamedCredentialParameter in Tooling API.

Can I use formula merge fields in HTTP headers with modern SecuredEndpoint NamedCredentials?

Yes. Instead of setting allowMergeFieldsInHeader on a Legacy NamedCredential, define a CustomHeader parameter inside namedCredentialParameters (or an AuthHeader on ExternalCredential) using a formula expression.

What is PrivateEndpoint in namedCredentialType?

Setting namedCredentialType to PrivateEndpoint routes outbound HTTP callouts over an AWS PrivateLink OutboundNetworkConnection rather than the public internet.