Trusted URLs
A Trusted URL is an entry on the Trusted URLs Setup page that adds an external origin to your org's Content Security Policy (CSP) allowlist.
Definition
A Trusted URL is an entry on the Trusted URLs Setup page that adds an external origin to your org's Content Security Policy (CSP) allowlist. The entry tells the browser that Lightning pages, Aura components, Lightning web components, and (when configured) Visualforce may load specific resource types from that origin, such as scripts, styles, images, fonts, frames, or media.
By default, Salesforce sends a strict CSP that only permits content from your own org over HTTPS. Anything from a third-party domain is blocked until you list it here. Trusted URLs was previously called CSP Trusted Sites, and the underlying metadata type is still named CspTrustedSite.
How Trusted URLs widen the Content Security Policy
What CSP blocks by default
Content Security Policy is a W3C standard that lets a server tell the browser which origins may supply content for a page. Salesforce uses it to reduce the blast radius of cross-site scripting and other injection attacks. The default policy is deliberately tight. References to external fonts, images, frames, and stylesheets must use HTTPS. Inline script is disallowed because unsafe-inline is not permitted for the script-src directive. External JavaScript libraries cannot be pulled from a CDN at runtime; you upload them as static resources so they load from your own origin under script-src 'self'. Other resource types (fonts, images, media, frame content, CSS) also default to 'self'. This is why a component that worked on a developer's laptop can fail in production the moment it reaches for a third-party host. The browser sees an origin that is not on the allowlist and refuses the request. Trusted URLs is the supported way to relax that default for the specific origins your org genuinely needs, without turning off the protection for everything.
Adding an entry in Setup
You manage these from Setup. In the Quick Find box, type Trusted URLs and open the Trusted URLs page, then click New Trusted URL. Each entry has an API Name (a unique developer name), a URL (the origin you are allowing, https://example.com), and an Active checkbox so you can stage an entry before it takes effect. You then pick a CSP Context that scopes where the entry applies: All, Lightning Experience, Experience Cloud sites (formerly Communities), or Visualforce. After the context, you choose the CSP directives the origin is allowed to satisfy. An entry is not a blanket pass; you tick only the resource types this origin should serve. If you enabled the Permissions-Policy header in Session Settings, the same page lets you grant browser features (such as camera or microphone) to that origin. Because the entry maps to the CspTrustedSite metadata type, you can also create and deploy these through change sets, packages, or the Metadata and Tooling APIs, which keeps allowlist changes under source control.
The CSP directives you can grant
Each checkbox on the entry corresponds to one CSP directive, and each directive covers a single class of resource. Tick connect-src to let the origin be reached through script interfaces, which covers fetch, XHR, and WebSocket connections from your components to that host. Tick frame-src to allow content embedded in iframe elements from the origin. Tick img-src to load images, style-src to load stylesheets, font-src to load web fonts, and media-src to load audio and video. The rule of thumb is to enable only what the integration actually uses. A weather widget that draws an iframe needs frame-src but probably not connect-src. An API your Lightning web component calls with fetch needs connect-src and nothing else. Granting extra directives quietly widens what that origin can do inside your pages, so treat every checkbox as a small permission grant. When a resource still fails after you add an entry, the usual cause is the wrong directive: the origin is trusted for images but the page is trying to frame it.
Reading the violations list before you widen
Guessing which origins to add is risky, so Salesforce gives you data. The Trusted URL and Browser Policy Violation List in Setup records each unique violation from the last seven days. Every row names the origin, the directive involved (img-src, font-src, frame-src, and so on), and an impact value. Blocked means the policy was enforced and the resource was actually stopped. Reported means the request went through under the current policy but would be blocked under a stricter one. Salesforce sometimes turns on the Content-Security-Policy-Report-Only header so it can surface what would break before tightening the real policy, and those conditional cases show up as report-only. Use this list as your work queue. If a legitimate integration is being blocked, add a precise Trusted URL with just the directive named in the violation. If a row points at an origin nobody recognizes, that is a signal to investigate rather than allowlist. Redirect violations also appear here, but those are governed by a separate Trusted URLs for Redirects allowlist, not by CSP directives.
Why a narrow allowlist matters
The whole point of CSP is to limit which outside code can influence your pages, so a sloppy allowlist gives back the protection you were trying to keep. The common failure mode is reactive widening: something breaks, an admin adds a broad origin with every directive ticked to make the error go away, and the entry never gets revisited. Each addition expands the attack surface. If one of those trusted hosts is ever compromised, it can now serve script, frames, or styles straight into your Lightning pages. Keep entries as specific as the host allows, prefer an exact subdomain over a parent domain, and turn on only the directives the use case demands. There is also a hard ceiling to respect. Salesforce advises keeping the CSP header under 12 KB, and customers report problems as it approaches 16 KB, partly because intermediaries and third parties can add to the header in transit. A long allowlist is therefore both a security cost and a reliability cost, which is one more reason to prune it.
Where Trusted URLs fits among related controls
Trusted URLs is one of several allowlists, and mixing them up wastes hours. It governs CSP: which origins the browser may load resources from inside Salesforce-rendered pages. It does not authorize server-side callouts. When Apex makes an outbound HTTP request, the endpoint must be listed under Remote Site Settings or, better, fronted by a Named Credential. CORS is yet another control: the CORS allowlist tells Salesforce which external sites may call Salesforce APIs from the browser, which is the opposite direction of traffic from Trusted URLs. A single integration can touch more than one. An Experience Cloud page that calls a partner API with fetch may need a Trusted URL with connect-src so the browser permits the request, plus a CORS entry on the partner side, plus credentials handled by a Named Credential if Apex is involved. Knowing which allowlist owns which hop is the difference between a five-minute fix and a long afternoon of guesswork. Trusted URLs owns the browser-load hop, nothing more.
Add a Trusted URL in Setup
Add an origin to the CSP allowlist so Lightning and Experience Cloud pages can load resources from it. Check the violations list first to confirm the exact origin and directive you need.
- Open the Trusted URLs page
From Setup, type Trusted URLs in the Quick Find box and select Trusted URLs. Review the Trusted URL and Browser Policy Violation List to see which origins and directives are being blocked.
- Create the entry
Click New Trusted URL. Give it a clear API Name, enter the exact origin in the URL field (https and a specific subdomain where possible), and leave Active selected when you want it live.
- Set context and directives
Choose the CSP Context (All, Lightning Experience, Experience Cloud sites, or Visualforce). Tick only the CSP directives the integration uses, such as connect-src for fetch calls or frame-src for embedded iframes.
- Save and verify
Save the entry, then reload the affected page and confirm the resource loads. Re-check the violations list after a day to make sure the blocked entry clears and no new origin appears.
Unique developer name for the entry, used by the CspTrustedSite metadata and in packaging.
The external origin you are allowing, entered as an HTTPS URL; prefer a precise subdomain over a parent domain.
Where the entry applies: All, Lightning Experience, Experience Cloud sites, or Visualforce.
The resource types this origin may serve, chosen as checkboxes (connect-src, frame-src, img-src, style-src, font-src, media-src).
- Adding the origin but ticking the wrong directive is the top reason a resource still fails; match the directive to the violation row.
- Remote Site Settings and Named Credentials cover Apex server-side callouts, not browser loads; a Trusted URL will not authorize an Apex callout.
- Keep the total CSP header under 12 KB; problems appear near 16 KB because third parties can add to the header in transit.
- The Active checkbox lets you stage an entry, but an inactive entry does nothing, so confirm it is active before testing.
Trust & references
Cross-checked against the following references.
- Manage Trusted URLsSalesforce
- Manage Trusted URL and Browser Policy ViolationsSalesforce
Straight from the source - Salesforce's reference material on Trusted URLs.
Hands-on resources to go deeper on Trusted URLs.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the primary benefit of Trusted URLs for Salesforce administrators?
Q2. Why is understanding Trusted URLs important for Salesforce admins?
Q3. Can a Salesforce admin configure Trusted URLs without writing code?
Discussion
Loading discussion…