๐งฑ The Core Concept: Server vs. Browser
Developers constantly confuse these two settings because they both involve whitelisting external URLs. The key to never mixing them up again is focusing on where the request originates.
๐ Key Points
- Remote Site Settings authorize SERVER-SIDE requests. When your Apex code uses
Http.send()to reach an external API, Salesforce checks this list. - Named Credentials are the modern replacement. If you use a Named Credential to handle an authenticated Apex callout, you do not need a separate Remote Site Setting.
- CSP Trusted Sites authorize BROWSER-SIDE requests. When your LWC or Aura component uses a javascript
fetch(), loads a remote script, or embeds an image, the browser's Content Security Policy (CSP) blocks it by default. A CSP Trusted Site tells the browser it is safe. - Don't forget CORS! If your LWC makes a browser-side fetch request, adding a CSP Trusted Site is only half the battle. The external server must also whitelist your Salesforce domain in its CORS (Cross-Origin Resource Sharing) settings.
⚖️ Quick Comparison Table
| Feature | Remote Site Setting | CSP Trusted Site |
|---|---|---|
| Governs | Apex server callouts | Browser (LWC/Aura) requests |
| Needed For | Http.send() to a raw URL |
fetch(), remote scripts, images |
| Replaced By | Named Credentials | (Still actively required) |
| Also Needs | — | Remote server's CORS allowlist |
fetch() error. Adding the wrong setting fixes nothing and shows a lack of understanding regarding client-side vs. server-side architecture.
Rule: Remote Site Settings authorize the server. CSP Trusted Sites authorize the browser.
Gain: Knowing which door is shut turns a confusing, hair-pulling failure into a 30-second fix.
Price: Because they sound similar, teams often guess, add the wrong one, and incorrectly conclude the platform is broken.
Limits: A Named Credential beautifully replaces the need for a Remote Site Setting for authenticated API calls. However, there is no replacement for a CSP entry when loading remote assets in a browser.
Best Practice: Instead of loading a 3rd-party library from a remote CDN (which requires CSP), download it, upload it as a Salesforce Static Resource, and load it locally. This bypasses the CSP headache completely.
๐ฌ Core Q&A
Q: An LWC calls an external API directly using JavaScript fetch() and it's blocked. Which setting fixes it, and why isn't a Remote Site Setting enough?
Because the browser is making the request, you actually need two things to succeed:
- A CSP Trusted Site: This adds the external origin to your Salesforce page's Content Security Policy. This gives your page permission to call out.
- CORS Configuration: The remote server must have Cross-Origin Resource Sharing (CORS) configured to accept requests from your specific Salesforce domain. This gives their server permission to respond.
A Remote Site Setting is useless here because the request never touches the Apex server. However, if this API requires a secret API key or authentication, making a browser-side fetch() is a massive security vulnerability anyway. You should route the request through Apex using a Named Credential to keep secrets safely on the server.
// ✅ Server Path (Preferred & Secure)
// Uses Apex callout → Named Credential
// Requires NO Remote Site Setting (Named Cred covers it)
// ❌ Browser Path (Public APIs Only)
// LWC direct fetch
// Requires CSP Trusted Site (Salesforce side) + CORS (Remote side)
const res = await fetch('https://api.public-data.com/v1/rates');
const data = await res.json();
๐ Scenario-Based Follow-Ups
Q1: You added a Remote Site Setting, but your Apex callout still fails with an 'Unauthorized endpoint' error. What did you miss?
There are a few common culprits here. First, if you are referencing a Named Credential in your code (e.g., callout:MyAPI), ensure the Named Credential actually exists and is configured correctly. Second, check for a strict URL mismatch. Your Remote Site Setting must exactly match the protocol and host (e.g., https vs http, or a missing subdomain). Finally, if the remote API redirects your call to a different domain, that secondary domain also needs to be whitelisted. Pro Tip: Upgrading the integration to use a Named Credential solves all of this automatically.
Q2: A third-party JS charting library in your LWC refuses to load. How do you diagnose the CSP issue?
Start by opening your browser's developer console. A CSP violation will clearly state the blocked directive (usually script-src or connect-src) and the specific origin URL. If it's a remote script, you can add that URL as a CSP Trusted Site.
However, the vastly superior Salesforce pattern is to download the JS library, upload it as a Static Resource, and load it via platformResourceLoader. This eliminates the remote fetch, negates the need for a CSP entry, and ensures the library is version-controlled alongside your app. Also, remember that if the library relies heavily on eval(), it might be strictly blocked by Lightning Web Security (LWS) regardless of your CSP settings.
Q3: Do I need both a CSP Trusted Site and CORS configuration for an LWC fetch request?
Yes! This is a very common point of confusion. CSP Trusted Sites govern what your Salesforce page is allowed to reach out to (an outbound rule). CORS is configured on the external server and governs who is allowed to read its data (an inbound rule). If you add a CSP Trusted Site but the external API owner doesn't whitelist your Salesforce URL in their CORS policy, the browser will still block the request.