CORS is one of those things every web developer runs into sooner or later. Most of us know how to fix it — add a header, change a config, ask the backend person to "do something about CORS." But how many of us actually understand what the browser is doing in the background, and why it's doing it?

Let's go through it today, slowly, with a simple example.

What's an "origin"?

Before we get into CORS, there's one word we need to pin down: origin. An origin is three things put together — the scheme, the host, and the port of a URL.

So https://example.com and http://example.com are different origins because the scheme is different (https vs http). https://example.com and https://api.example.com are different because the host is different. And https://example.com and https://example.com:8080 are different because the port is different. If any one of those three pieces changes, the browser treats it as a separate origin.

This matters because the browser treats every origin as its own little sandbox. Whatever happens inside one origin is supposed to stay inside that origin.

The browser's default rule

By default, JavaScript running on one origin is not allowed to read data from another origin. This rule has a name: same-origin policy. Every modern browser ships with it built in, and it's the foundation that everything else here is built on.

Without it, the web would be terrifying. Imagine you're logged into your bank in one tab. In another tab, you visit some random site. If same-origin policy didn't exist, that random site could just do this in the background:

fetch('https://yourbank.com/api/balance')
  .then(res => res.json())
  .then(data => sendToAttacker(data))

The browser would happily send the request, attach your bank cookies (because the cookies belong to the bank's domain), and the bank would return your balance to whoever asked. The random site's JavaScript would then read the response and send it anywhere it wanted. Every site you visit would be able to scrape every site you're logged into.

Same-origin policy stops that. The browser still sends the request, but it refuses to let the random site's JavaScript read the response. The request happens; the response gets blocked from reaching the calling code.

So what is CORS?

CORS stands for Cross-Origin Resource Sharing, and it's the mechanism a server uses to say "actually, it's fine, this other origin is allowed to read my response." It's an opt-in to relax same-origin policy in cases where cross-origin access is legitimate.

The most common case is your own setup. Your frontend lives at app.example.com, your API lives at api.example.com. Different origins, so same-origin policy would block the frontend's calls by default. CORS is how your API tells the browser "yes, app.example.com is allowed."

How does the API tell the browser that? Through a response header:

Access-Control-Allow-Origin: https://app.example.com

When the browser sees this header on the response, it lets your JavaScript read it. Without it, the response is blocked and you see a CORS error in the console.

One thing worth noticing here, because it confuses a lot of people: if your frontend and API are on the same origin during development — say both on localhost:3000 behind a Next.js rewrite — CORS doesn't kick in at all. The browser doesn't even check the headers, because nothing cross-origin is happening. CORS issues often only show up in production, when frontend and API are on different domains.

A simple example, end to end

Let's walk through one fetch from start to finish.

Your frontend at https://app.example.com does:

fetch('https://api.example.com/users')

Here's what actually happens:

1. The browser builds the request. It automatically adds a header: Origin: https://app.example.com. This is the browser telling the server "this request is coming from app.example.com."

2. The browser sends the request to api.example.com. The server receives it like any other request and processes it. It can read the database, run business logic, return data — whatever. From the server's point of view, this is a normal request.

3. The server sends a response back, say with the user list as JSON.

4. The browser receives the response and checks the headers. Specifically, it looks at Access-Control-Allow-Origin. If that header is missing, or if its value doesn't match https://app.example.com (or *), the browser blocks the response. The JavaScript that called fetch sees a CORS error, and the response body is never delivered to your code.

5. If the header is present and matches, the browser hands the response to the JavaScript, and your code continues normally.

This is the part that most explanations of CORS skip over: the server doesn't refuse the request. The browser does. The server returned a perfectly fine response. The browser refused to hand it to the JavaScript because the server didn't include the right header saying "this origin is allowed."

That's also why you can hit the same API from curl, from Postman, or from a server-to-server call and it just works. CORS only exists in browsers. Other clients don't enforce same-origin policy, so there's nothing to block.

What about complex requests? Preflight

For "simple" requests — basically GETs and a few POSTs with safe content types — the browser sends the actual request directly and checks the response headers afterwards.

But for anything more involved — a PUT, a DELETE, a request with a custom header like Authorization, or a JSON-typed POST — the browser does an extra step first. It sends a preflight request.

A preflight is an OPTIONS request to the same URL, sent before the real one. It looks like:

OPTIONS /users HTTP/1.1
Origin: https://app.example.com
Access-Control-Request-Method: DELETE
Access-Control-Request-Headers: Authorization, Content-Type

The browser is essentially asking the server: "I'm about to send a DELETE with these headers. Are you okay with that?"

The server responds with what it allows:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type

If the browser is happy with the preflight response, it then sends the real request. If the preflight fails, the real request never goes out at all.

This is why you sometimes see two requests in the network tab for what looks like a single fetch. The first is the preflight; the second is the actual call.

The credentials catch

There's one extra rule worth knowing, because it catches a lot of people off guard. If your frontend sends credentials with the request — cookies, an Authorization header, anything that identifies the user — like this:

fetch('https://api.example.com/me', {
  credentials: 'include',
})

Then a wildcard Access-Control-Allow-Origin: * is no longer enough. The browser refuses to deliver the response. The server has to name the specific origin it trusts, and add one more header:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true

The reason is security. If * worked alongside credentials, any malicious site could fire authenticated requests to your API. The browser would attach the user's cookies (because cookies belong to the API's domain, not the calling page's). The server would see "any origin is allowed" and respond. The malicious site's JavaScript would then read the response — and every authenticated API on the web would be one fetch away from being scraped.

So the rule is: * is fine for genuinely public APIs that don't care who's calling. As soon as authentication enters the picture, the server has to be explicit about which origins it trusts.

Wrapping up

Here's the whole picture in one line: the browser blocks cross-origin reads by default (same-origin policy), and CORS is the mechanism a server uses to opt in to allowing them, through response headers like Access-Control-Allow-Origin.

A few things worth remembering when you next see a CORS error in the console.

The browser is the one doing the blocking, not the server. The server happily sends the response either way; the browser decides whether your JavaScript gets to see it. That's why CORS errors only happen in the browser, never in curl or server-to-server calls.

For non-simple requests, the browser sends an OPTIONS preflight first to ask the server what's allowed. Two network requests for one fetch — that's why.

And if credentials are involved, the wildcard stops working. The server has to name the origin explicitly and add Access-Control-Allow-Credentials: true.

CORS isn't there to annoy developers. It's a security feature that protects users from sites that would otherwise be able to read their data from other sites. Once you see what it's protecting, the error messages start making more sense — and the fix usually comes down to figuring out exactly which header the browser wants to see, and making sure your server is sending it.