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:

• Server-side vs. browser-side: Remote Site Settings and CSP Trusted Sites are completely separate security controls for completely different scenarios. Remote Site Settings gate server-side Apex callouts. CSP Trusted Sites gate browser-side resource loading in Lightning components. Adding a URL to the wrong control does nothing.
• Most critical misconception: Adding an endpoint to CSP Trusted Sites does NOT fix a failing Apex Http.send() callout. Apex callouts are server-side — they are gated exclusively by Remote Site Settings, not CSP. This is the most common misdirection in Salesforce integration troubleshooting.
• Change Set gotcha: Remote Site Settings are deployable Metadata API components (type RemoteSiteSetting) but are NOT automatically included in Change Sets by default. Omitting them is the most common cause of Apex callout failures immediately after a production deployment.

---

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:

• Applied per org — not per user or per profile.
• URL matching is prefix-based: a Remote Site Setting for https://api.example.com covers all paths under that domain.
• Protocol matters: https://api.example.com and http://api.example.com are different entries.
• Remote Site Settings are metadata (type RemoteSiteSetting) and can be deployed via Metadata API, Change Sets, or SFDX.
• Remote Site Settings are NOT included in Change Sets by default — they must be manually added.

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:

• Applied per org at the browser level.
• Different directives control different resource types: connect-src for fetch/XHR, script-src for JavaScript, img-src for images.
• CSP Trusted Sites have NO effect on server-side Apex callouts (Http.send()).
• A Lightning component making an XHR/fetch call to an external API from the browser needs a CSP Trusted Site. An Apex class making the same call from the server needs a Remote Site Setting.

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

Situation	Correct Control	Why
Apex Http.send() failing with Unauthorized endpoint	Remote Site Setting	Apex callouts are server-side; only Remote Site Settings gate them
Lightning component fetch/XHR failing (browser error)	CSP Trusted Site	Browser-side resource loading is gated by CSP, not Remote Site Settings
Both Apex and Lightning need to call the same endpoint	BOTH Remote Site Setting AND CSP Trusted Site	Server-side and browser-side are separate gates
Apex callout working in sandbox, failing in production	Add Remote Site Setting to Change Set	Remote Site Settings not included in Change Sets by default
Need to disable HTTPS certificate validation	disableProtocolSecurity: true in metadata	Only for non-HTTPS or self-signed cert scenarios; security risk
Using Named Credentials for callouts	Not applicable — Named Credentials manage their own URL allowlist	Named Credentials replace Remote Site Settings for the configured endpoint

---

Recommended Workflow

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:

• Remote Site Setting added for every external URL called via Apex Http.send()
• CSP Trusted Site added for every external URL accessed by Lightning components in the browser
• Remote Site Settings explicitly included in any Change Set that includes Apex code using them
• Remote Site Setting metadata files included in Metadata API / SFDX deployment packages
• Apex callout tested successfully after configuration
• Named Credentials evaluated as an alternative (preferred over Remote Site Settings for credential management)

---

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

Artifact	Description
Remote Site Setting configuration	Setup > Security > Remote Site Settings entry for the external endpoint
CSP Trusted Site configuration	Setup > Security > CSP Trusted Sites entry for browser-side access
RemoteSiteSetting metadata XML	Deployable metadata file for SFDX/Change Set deployment
Change Set inclusion guide	Steps to add Remote Site Settings to a Change Set explicitly

---

Related Skills

• integration-admin-connected-apps — Configure connected apps for OAuth-based integration authentication
• integration-user-management — Set up the integration user whose callouts will use these settings