CORS
CORS (Cross-Origin Resource Sharing) in Salesforce is a Setup configuration where admins allowlist external web origins that the browser is permitted to use when calling Salesforce APIs from JavaScript.
Definition
CORS (Cross-Origin Resource Sharing) in Salesforce is a Setup configuration where admins allowlist external web origins that the browser is permitted to use when calling Salesforce APIs from JavaScript. Without an entry in the CORS allowlist, browsers block JavaScript code on https://app.example.com from making API calls to https://your-org.my.salesforce.com, even with valid OAuth tokens, because the cross-origin restriction is enforced at the browser level rather than the server level.
CORS exists because browsers enforce the same-origin policy by default to prevent malicious websites from reading data from arbitrary other domains using a user logged-in session. Salesforce inherits this. The CORS allowlist tells Salesforce to respond to preflight requests from your trusted origins with the headers that let the browser proceed with the actual request. CORS does not bypass authentication; it complements OAuth and session-based auth by telling the browser that this server is OK with cross-origin requests from this origin.
How CORS works in Salesforce
The Setup page and the allowlist record
Setup, CORS. The page lists allowed origin URLs and lets you add new ones. Each entry is the full origin including the scheme (https://app.example.com), not the path. Wildcards are limited: subdomain wildcards (https://*.example.com) work; path wildcards do not. Save the entry; the change takes effect on subsequent API calls.
The preflight and the response headers
For non-simple HTTP requests (most Salesforce API calls, because they use Authorization headers), the browser sends an OPTIONS preflight request before the actual request. Salesforce responds with Access-Control-Allow-Origin (echoing the origin from the allowlist), Access-Control-Allow-Methods (POST, GET, and others), and Access-Control-Allow-Headers (the headers the actual request will use). If the preflight matches, the browser proceeds; otherwise it blocks.
What CORS does not do
CORS controls browser behavior, not server-side auth. A request from an allowlisted origin still needs a valid session ID or OAuth token to authenticate. A request from a non-allowlisted origin will be blocked by the browser before it reaches Salesforce. Server-to-server calls (Node, Python, anything not running in a browser) bypass CORS entirely because there is no browser to enforce the same-origin policy.
Which Salesforce APIs honor CORS
The CORS allowlist applies to the REST API, Apex REST, Bulk API, Tooling API, External Web Services callout endpoints, and the Lightning Out hosted services. Visualforce pages and Lightning components running inside Salesforce do not need CORS entries because they are same-origin. Experience Cloud sites have their own CORS handling on the site domain.
Wildcard subdomain support
Salesforce accepts wildcard subdomain entries: https://*.example.com matches https://app.example.com, https://staging.app.example.com, and any other subdomain. The wildcard must be the leftmost subdomain segment; mid-string wildcards like https://app.*.example.com are not allowed. For multi-environment apps (dev, staging, prod), a single wildcard entry usually covers all.
Common CORS errors and how to read them
The most common error is "blocked by CORS policy: No Access-Control-Allow-Origin header is present on the requested resource." This means the origin is not in the allowlist; add it. Another common error is "preflight request does not pass access control check"; this usually means the request includes a header that is not in the Allow-Headers list on the Salesforce response, which is set automatically for standard headers but may need attention for custom headers.
CORS and Lightning Web Components in headless apps
For Lightning Web Components built as Open Source and deployed in a headless app (not running inside Salesforce), the CORS allowlist is essential. The LWC needs to call back to Salesforce, and without the allowlist, the browser blocks every request even though OAuth would succeed. This is the most common gotcha in modern Salesforce-LWC-external-app architectures.
How to add origins to the Salesforce CORS allowlist
Adding a CORS entry takes one click. The harder work is identifying the correct origin URL and verifying the request actually succeeds through the browser.
- Identify the exact origin URL
The origin is scheme plus host plus port. https://app.example.com is correct. www.example.com is wrong (no scheme). https://app.example.com/some/path is wrong (path included). Use the browser DevTools Network tab to confirm the exact origin if unsure.
- Open Setup, CORS
Setup, search CORS. The CORS Allowed Origins List page appears. Click New.
- Enter the origin URL
Paste the exact origin string. For multi-environment apps, consider a wildcard subdomain (https://*.example.com) to cover dev, staging, and prod with one entry.
- Save
The entry appears in the list. Changes are effective on the next request from that origin.
- Test from the browser
Open a browser with DevTools open. Trigger the cross-origin request from your app. Check the Network tab for the preflight OPTIONS request and the Access-Control-Allow-Origin response header.
- Handle the rare preflight failure
If you see a preflight failed error, inspect the request headers in DevTools. Compare them to the Salesforce response Access-Control-Allow-Headers. Add any missing custom headers to the application code or use a Salesforce-side proxy if Salesforce does not allow the header.
- CORS does not bypass authentication. A request from an allowlisted origin still needs valid OAuth tokens or session ID to authenticate.
- Path wildcards do not work. The CORS allowlist accepts scheme plus host plus port only.
- Server-to-server requests do not use CORS. If you are getting a CORS error, the request is coming from a browser; server-side code does not trigger it.
- Browser caching of preflight responses can mask CORS changes. Hard-reload (Ctrl+Shift+R) or clear the browser cache when testing changes.
- Subdomain wildcards work only on the leftmost subdomain. *.app.example.com is fine; app.*.example.com is not.
Trust & references
Cross-checked against the following references.
- Configure a CORS AllowlistSalesforce Help
- Salesforce REST API ResourcesSalesforce Developers
Straight from the source - Salesforce's reference material on CORS.
- CORS on MDNMDN Web Docs
- CORS OverviewSalesforce Help
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 required before deploying CORS-related code to production?
Q2. What is a Governor Limit in the context of CORS?
Q3. Where would a developer typically work with CORS?
Discussion
Loading discussion…