SfSkills Domains Docs GitHub

Home / admin / remote-site-settings

remote-site-settings

Use when configuring Remote Site Settings to allow Apex callouts to external URLs, or distinguishing them from CSP Trusted Sites for Lightning component resource loading. NOT for storing an endpoint and its auth as a Named Credential — use integration/named-credentials-setup. NOT for allow-listing a URL the browser itself loads (script, iframe, fetch) — use security/csp-and-trusted-urls.

Open the skill folder on GitHub

Remote Site Settings and CSP Trusted Sites

This skill activates when a practitioner needs to configure external endpoint access for Apex callouts (Remote Site Settings) or when troubleshooting the common confusion between Remote Site Settings (server-side Apex callout gate) and CSP Trusted Sites (browser-side Lightning component resource gate). It covers the most critical anti-pattern in this domain: adding a URL to CSP Trusted Sites to fix a failing Apex callout.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Remote Site Settings — Server-Side Apex Callout Gate

Remote Site Settings (Setup > Security > Remote Site Settings) are a platform-level allowlist that governs which external URLs Salesforce Apex code can call via Http.send(). Every external URL that an Apex class calls must have a matching Remote Site Setting registered, or the callout is denied at the platform level with a CalloutException: Unauthorized endpoint error.

Key characteristics:

CSP Trusted Sites — Browser-Side Lightning Component Gate

CSP Trusted Sites (Setup > Security > CSP Trusted Sites) configure the Content Security Policy header returned by Salesforce to the user's browser. CSP controls what external resources (scripts, styles, images, fonts, connections) Lightning components can load or call from the user's browser session.

Key characteristics:

Metadata API Deployment

Remote Site Settings are deployed as RemoteSiteSetting metadata type:

<!-- RemoteSiteSetting: ExternalPaymentGateway.remoteSite -->
<?xml version="1.0" encoding="UTF-8"?>
<RemoteSiteSetting xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Payment gateway endpoint for Apex callouts</description>
    <disableProtocolSecurity>false</disableProtocolSecurity>
    <isActive>true</isActive>
    <url>https://api.paymentgateway.com</url>
</RemoteSiteSetting>

Deploy via sf project deploy start or include in Change Set (must add explicitly in the "Add" tab under Remote Site Settings component type).

Common Patterns

Fixing a Failing Apex Callout

When to use: An Apex class using Http.send() throws CalloutException: Unauthorized endpoint, please check Setup>Security>Remote Site Settings.

How it works:

  1. Identify the exact URL being called in the Apex code (including protocol and domain).
  2. Navigate to Setup > Security > Remote Site Settings.
  3. Click New Remote Site.
  4. Enter a name (alphanumeric, no spaces), the URL (e.g., https://api.example.com), and optionally a description.
  5. Check "Disable Protocol Security" only if the external service uses HTTP (not HTTPS) — leave unchecked for HTTPS.
  6. Save and test the Apex callout.

Including Remote Site Settings in a Change Set

When to use: Deploying Apex code that makes callouts from sandbox to production via Change Set.

How it works:

  1. In the Change Set, click Add.
  2. Under Component Type, select "Remote Site Setting."
  3. Add each required Remote Site Setting.
  4. Deploy the Change Set — the Remote Site Setting will be created in the target org.

If Remote Site Settings are not in the Change Set, the Apex code deploys successfully but callouts immediately fail in production with Unauthorized endpoint errors.

Decision Guidance

SituationCorrect ControlWhy
Apex Http.send() failing with Unauthorized endpointRemote Site SettingApex callouts are server-side; only Remote Site Settings gate them
Lightning component fetch/XHR failing (browser error)CSP Trusted SiteBrowser-side resource loading is gated by CSP, not Remote Site Settings
Both Apex and Lightning need to call the same endpointBOTH Remote Site Setting AND CSP Trusted SiteServer-side and browser-side are separate gates
Apex callout working in sandbox, failing in productionAdd Remote Site Setting to Change SetRemote Site Settings not included in Change Sets by default
Need to disable HTTPS certificate validationdisableProtocolSecurity: true in metadataOnly for non-HTTPS or self-signed cert scenarios; security risk
Using Named Credentials for calloutsNot applicable — Named Credentials manage their own URL allowlistNamed Credentials replace Remote Site Settings for the configured endpoint

Step-by-step instructions for an AI agent or practitioner working on this task:

  1. Identify the error type — Determine whether the failing call is from Apex server-side code (Http.send()) or from a Lightning component in the user's browser (fetch, XHR, img.src). The error source determines which control to configure.
  2. For Apex callout failures — Navigate to Setup > Security > Remote Site Settings. Verify the calling URL is registered. If not, add a new Remote Site Setting with the exact protocol and domain.
  3. For Lightning component resource failures — Navigate to Setup > Security > CSP Trusted Sites. Add a new trusted site entry for the external URL with the appropriate directive (connect-src for XHR/fetch, script-src for scripts).
  4. For Change Set deployments — In the Change Set, explicitly add each Remote Site Setting under component type "Remote Site Setting" before uploading. Do not assume metadata deployment of Apex automatically includes the Remote Site Settings it depends on.
  5. For Metadata API / SFDX deployments — Include RemoteSiteSetting metadata files in the deployment package. The file name must match the Remote Site Setting name in the org.
  6. Test the callout — After adding the Remote Site Setting, test the Apex callout (via anonymous Apex or the relevant trigger/class). Confirm no CalloutException: Unauthorized endpoint error.
  7. Document the dependency — Add a comment near the Apex callout code indicating which Remote Site Setting is required. This prevents future Change Set deployments from omitting it.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Adding a URL to CSP Trusted Sites does not fix a failing Apex callout — Apex Http.send() is a server-side call. CSP controls browser-side resource loading. They are completely separate. A CSP Trusted Site entry for an endpoint does nothing to unblock an Apex callout to the same endpoint. This is the single most common misdirection in Salesforce integration troubleshooting, confirmed by the number of support cases and community posts following this path.
  2. Remote Site Settings not included in Change Sets by default — When assembling a Change Set that includes Apex classes making external callouts, the Remote Site Settings those classes depend on must be explicitly added as a separate component type. The Change Set tool does not automatically detect or include them as a dependency. This is the most common cause of Apex callout failures in production immediately after a Change Set deployment.
  3. Protocol in URL matters — http:// and https:// are separate entries — A Remote Site Setting for https://api.example.com does not cover http://api.example.com, and vice versa. If the Apex code uses HTTPS but the Remote Site Setting was created with HTTP (or the URL was entered without the correct protocol), the callout fails. Always verify the exact protocol in the callout URL matches the Remote Site Setting.

Output Artifacts

ArtifactDescription
Remote Site Setting configurationSetup > Security > Remote Site Settings entry for the external endpoint
CSP Trusted Site configurationSetup > Security > CSP Trusted Sites entry for browser-side access
RemoteSiteSetting metadata XMLDeployable metadata file for SFDX/Change Set deployment
Change Set inclusion guideSteps to add Remote Site Settings to a Change Set explicitly

Package files