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.com and api.example.com are 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.com
  • https://api.example.com

Different host, different origin. CORS applies.

Same-site is broader. It’s about the registrable domain, roughly:

  • app.example.com
  • api.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:

  1. app.example.com to api.example.com is cross-origin
  2. cross-origin fetch needs valid CORS
  3. credentialed cross-origin fetch needs a specific allowed origin, not *
  4. 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();
}

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.

  • 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.