A lot of CORS bugs are not really CORS bugs.
They’re architecture bugs caused by mixing up same-origin and same-site, then trying to patch the fallout with headers until the browser stops complaining.
I’ve seen this play out the same way more than once:
- frontend on
app.example.com - API on
api.example.com - session cookie involved
- somebody says “it’s the same domain, so it should work”
- someone else adds
Access-Control-Allow-Origin: * - auth breaks, or worse, security assumptions break
Here’s a real-world style case study that shows how teams end up here, what the browser is actually doing, and what the fix looks like.
The setup
A SaaS team had this stack:
- Marketing site:
https://www.example.com - App SPA:
https://app.example.com - API:
https://api.example.com
They wanted the SPA to call the API with a session cookie.
Their mental model was:
app.example.comandapi.example.comare the same site, so browser security shouldn’t care much.
That sentence contains the bug.
Same-site is not same-origin
These two terms get mashed together constantly, but they solve different problems.
Same-origin means the full tuple matches:
- scheme
- host
- port
So these are different origins:
https://app.example.comhttps://api.example.com
Different host, different origin. CORS applies.
Same-site is broader. It’s about the registrable domain, roughly:
app.example.comapi.example.com
These are usually considered same-site because they share example.com.
That matters for cookie behavior, especially SameSite, but it does not mean the browser skips same-origin policy. It won’t.
This is the trap: cookies may be eligible to flow in a same-site context, while JavaScript access is still blocked by same-origin rules unless CORS is configured correctly.
What they shipped first
The frontend used fetch:
async function loadAccount() {
const res = await fetch("https://api.example.com/account", {
credentials: "include",
});
if (!res.ok) throw new Error("Request failed");
return res.json();
}
On the API, they added:
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
And they expected the browser to send the session cookie and return JSON.
Instead, they got the classic browser error:
The value of the ‘Access-Control-Allow-Origin’ header must not be ‘*’ when the request’s credentials mode is ‘include’
That part is straightforward. If you send credentials, * is not allowed.
But then the team made a worse assumption:
Fine, CORS is just blocking the response. The request still reaches the server, so auth should still work.
Sometimes yes, sometimes no, and betting your auth model on that distinction is how systems get weird fast.
The deeper confusion
Their login cookie looked like this:
Set-Cookie: session=abc123; Path=/; Secure; HttpOnly; SameSite=Lax
They assumed:
- same-site subdomains
- secure cookie
- credentials included
- therefore cookie should be sent
But the browser behavior around cookies, fetch, navigation, and site context is subtle enough that “same-site” alone is not a reliable design principle.
What mattered in practice was this:
app.example.comtoapi.example.comis cross-origin- cross-origin
fetchneeds valid CORS - credentialed cross-origin
fetchneeds a specific allowed origin, not* - cookie policy still has to line up with the request context
The team kept toggling cookie flags and CORS headers without separating these concerns.
Before: the broken implementation
Here was the actual “before” state in Express:
import express from "express";
import cookieParser from "cookie-parser";
const app = express();
app.use(cookieParser());
app.use(express.json());
app.use((req, res, next) => {
res.setHeader("Access-Control-Allow-Origin", "*");
res.setHeader("Access-Control-Allow-Credentials", "true");
res.setHeader("Access-Control-Allow-Headers", "Content-Type");
res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
if (req.method === "OPTIONS") {
return res.sendStatus(204);
}
next();
});
app.get("/account", (req, res) => {
if (!req.cookies.session) {
return res.status(401).json({ error: "Not authenticated" });
}
res.json({ email: "[email protected]", plan: "pro" });
});
app.listen(3000);
This had three problems:
1. Wildcard origin with credentials
That simply doesn’t work in browsers for credentialed requests.
2. No origin allowlist
Any origin could attempt a request. The browser wouldn’t expose all responses, but the server policy was still sloppy and misleading.
3. The team was using CORS as auth glue
They were trying to “make cookies work” by changing CORS. CORS is not an authentication system. It’s a browser read policy layered on top of HTTP.
The symptom that wasted the most time
The API worked fine in Postman and curl:
curl -i https://api.example.com/account \
-H "Cookie: session=abc123"
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{"email":"[email protected]","plan":"pro"}
So backend engineers said, “API is good.”
Frontend engineers said, “Browser is broken.”
Neither was right. The browser was enforcing exactly what they told it to enforce.
When I’m debugging this kind of issue, I like checking raw response headers in a clean way before guessing. A tool like HeaderTest is handy for seeing what’s actually coming back, especially when multiple proxies and CDNs are involved.
After: the fixed implementation
The fix started with a rule:
Treat cross-origin subdomain requests as cross-origin, even if they are same-site.
That mental reset solved most of it.
Correct CORS for a credentialed SPA
import express from "express";
import cookieParser from "cookie-parser";
const app = express();
const allowedOrigins = new Set([
"https://app.example.com",
]);
app.use(cookieParser());
app.use(express.json());
app.use((req, res, next) => {
const origin = req.headers.origin;
if (origin && allowedOrigins.has(origin)) {
res.setHeader("Access-Control-Allow-Origin", origin);
res.setHeader("Vary", "Origin");
res.setHeader("Access-Control-Allow-Credentials", "true");
res.setHeader("Access-Control-Allow-Headers", "Content-Type");
res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
}
if (req.method === "OPTIONS") {
return res.sendStatus(204);
}
next();
});
app.get("/account", (req, res) => {
if (!req.cookies.session) {
return res.status(401).json({ error: "Not authenticated" });
}
res.json({ email: "[email protected]", plan: "pro" });
});
app.listen(3000);
And the frontend stayed simple:
async function loadAccount() {
const res = await fetch("https://api.example.com/account", {
credentials: "include",
});
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
return res.json();
}
Cookie settings that matched the architecture
They also made the cookie policy explicit and tested it in the browser they actually supported:
Set-Cookie: session=abc123; Path=/; Secure; HttpOnly; SameSite=Lax
For same-site subdomain flows, that can be fine, depending on the exact request patterns. If you’re crossing true third-party boundaries, that’s a different story and usually means SameSite=None; Secure.
The key point is this: cookie policy and CORS policy are related but separate. One decides whether the browser may send credentials. The other decides whether frontend JavaScript may read the response.
What changed after the fix
Before:
- browser sent preflight
- API returned
Access-Control-Allow-Origin: * - browser rejected credentialed response
- frontend saw a CORS failure
- team kept arguing about cookies
After:
- browser sent
Origin: https://app.example.com - API echoed that exact origin
- API sent
Access-Control-Allow-Credentials: true - browser allowed the response
- frontend got JSON
- auth worked consistently
Why same-site still matters
Same-site isn’t useless. It matters a lot for cookies and CSRF thinking.
But it does not relax same-origin policy for XHR or fetch.
That’s the core confusion.
A request can be:
- same-site
- cross-origin
- credentialed
- subject to CORS
All at the same time.
If that sounds annoying, it is. But once your team stops trying to collapse these ideas into one, the bugs get easier to reason about.
A useful reality check: GitHub’s public API
If you want to see what deliberate CORS looks like for a public API, look at api.github.com.
Real headers include:
access-control-allow-origin: *
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset, Warning
That makes sense because it’s a public API model. Wildcard origin is fine there because they’re not relying on browser cookies for authenticated session sharing in the way this SaaS app was.
The exposed headers are also the giveaway that they’re thinking carefully about what browser JavaScript should be able to read beyond the safelisted response headers.
That’s a very different setup from “my SPA on one subdomain needs session auth on another subdomain.”
The lessons that stuck
Here’s the checklist I now use for this class of bug:
1. Ask “same-origin or same-site?” immediately
If the hosts differ, treat it as cross-origin. Full stop.
2. Don’t use * for credentialed requests
If cookies or HTTP auth are involved, return a specific origin and set Vary: Origin.
3. Separate cookie debugging from CORS debugging
- Cookie issue: is the browser sending credentials at all?
- CORS issue: is the browser allowing JS to read the response?
Those are different questions.
4. Test in a browser, not just curl
curl proves your server speaks HTTP. It does not prove your browser integration works.
5. Be careful with security-header sprawl
Teams that are confused about CORS are often also confused about CSP, CORP, COEP, and friends. Different controls, different threat models. If you’re tightening broader header policy too, csp-guide.com is a good reference.
The practical takeaway is simple: same-site cookies do not make two origins the same origin. Once you stop expecting them to, your CORS config gets a lot cleaner and your auth flow gets a lot less mysterious.