CORS in the web

What is CORS?

When your JavaScript on mysite.com calls fetch("https://api.othersite.com/data"), whose permission actually matters — yours, the other server's, or someone standing between the two? Most people assume that if a reply comes back, it is simply theirs to read. It is worth pausing on that assumption, because the whole of CORS hangs on why it is not quite true.

Consider that your code and the far server never really speak directly — the browser sits in the middle and carries every request on your behalf. So suppose a stranger's page, opened in the same browser where you are logged into your bank, could quietly fetch yourbank.com/account, riding on your logged-in cookies, and read the reply. What might go wrong there? That precise worry is the thing CORS exists to answer. Notice how the danger only appears because the browser is shared and trusted.

Sit with that middle step, because it is the root of everything else. A cookie is attached by the browser to any request bound for the host that set it, without asking the page that triggered the request whether it deserves that authority. Your logged-in session is therefore not a possession of your bank's page; it is an ambient power the browser wields on behalf of whatever happens to be running in it. If reading cross-origin replies were free, every page you visited while logged in anywhere could read your mail and your balance simply by asking. So the browser adopted a blunt default — the same-origin policy — under which a script may read only what came from its own scheme, host and port.

But blunt defaults break honest cases: a public weather API, a company's own front end talking to its own API on another subdomain. What would you need in order to relax the rule safely? Only one thing: some way for the server whose data is at stake to say so. It cannot be the requesting page that decides, since a hostile page would grant itself permission; and it cannot be the browser guessing, since the browser has no idea which cross-origin reads are innocent. The permission must come from the far end — and that is all CORS is.

One more question then follows on its own. Some requests are dangerous merely to send — a DELETE on a record, a PUT with a JSON body. Should the browser fire those off and only afterwards discover it was not allowed to show you the answer? It does not. For anything outside a small "simple" set it sends an OPTIONS request first, naming the method and headers it intends to use, and withholds the real request entirely unless the answer comes back affirmative.

That note is a response header the far server chooses to send: Access-Control-Allow-Origin. The decision sits with the destination server, openly declaring which origins may read its replies — not with your code, and not with the browser's guess.

The advance telephone call has a name and a shape. It is a preflight: a real OPTIONS request the browser makes on its own initiative, carrying Access-Control-Request-Method and, where relevant, Access-Control-Request-Headers. Anything outside the "simple" set triggers it — a GET or a form-style POST slips through, while a PUT, a DELETE, a custom header like X-Api-Key, or a POST with Content-Type: application/json all provoke one. The server must answer with matching Access-Control-Allow-Methods and Access-Control-Allow-Headers.

Now the misconception worth correcting, which is where most debugging time goes. A CORS error usually does not mean your request was blocked. Unless a preflight failed, the server received it and acted; the browser merely refused to let your script read the answer. That has a consequence people find genuinely surprising: CORS is no defence against a hostile page sending requests to your API. A form on any site can POST to yours with your users' cookies attached and no CORS header will prevent it — which is why cross-site request forgery needs its own defences, and why a write endpoint that trusts a request simply because it arrived is unsafe whatever its CORS configuration says.

And one framing that clears up much of the frustration: CORS does not add protection. The protection was the same-origin policy, which came first and is the default; CORS is the mechanism for relaxing it. So a permissive setting is not turning security on, it is turning a restriction off, and Access-Control-Allow-Origin: * on an endpoint returning anything private is a hole rather than a convenience — which is also why the browser refuses to honour the wildcard at all once credentials are involved.

• What credentials (cookies) change about that note, and why credentials: "include" raises the bar.
• Why a wildcard Access-Control-Allow-Origin: * stops being allowed the moment credentials are involved.
• How preflight caching (Access-Control-Max-Age) reduces the number of scout trips.
• How cross-site request forgery attacks the gap CORS deliberately leaves open.

Every term the collection defines is gathered in the glossary.