CORS & cross-origin requests

The browser checks for permission

A web page can load many things from other websites: images, fonts, scripts, and data. Loading is one thing. Reading is another. When your JavaScript wants to read an answer from another website, the browser first checks for permission.

That permission system is called CORS. The letters stand for Cross-Origin Resource Sharing. "Cross-origin" means "from a different website". You'll see the exact meaning of "origin" in the next section.

CORS is not new JavaScript syntax. It is also not an option you add to fetch. It works like this:

1. Your page sends a request to a server. A request is a message that asks for something.
2. The server sends back a response: the answer.
3. The response carries headers. A header is a short line of extra facts, written as a name and a value, such as Content-Type: application/json.
4. The browser looks for one header, Access-Control-Allow-Origin. It says which website may read the response.
5. If that header is missing, or names a different website, the browser does not give the response to your code.

An origin is three parts of a URL:

• The scheme: http or https.
• The host: the site's name, like example.com.
• The port: a number that picks a door on the server, like 3000. If the URL doesn't show one, https uses 443 and http uses 80.

The origin of https://example.com:443/products?q=shoes is https://example.com. The port 443 is the default for https, so it is left out. The path /products and the query ?q=shoes are not part of the origin.

The same-origin policy is a safety rule in every browser. JavaScript may read answers from its own origin. To read an answer from a different origin, it needs CORS permission.

Why? Any site you visit can run JavaScript in your browser. Without this rule, a random site could quietly read your bank page or your company's private pages, because your browser is signed in to them.

const app = new URL("http://shop.example:3000/cart");
const api = new URL("https://shop.example:3000/cart");
const store = new URL("http://www.shop.example:3000/cart");

console.log(app.origin === api.origin);
console.log(app.origin === store.origin);
console.log(new URL("http://shop.example:3000").origin === new URL("http://shop.example:5173").origin);

new URL(...) reads a URL and splits it into parts. Its .origin property is the origin as text.

• Line 5 compares http with https. The schemes differ, so it prints false.
• Line 6 compares shop.example with www.shop.example. The hosts differ, so it prints false.
• Line 7 compares port 3000 with port 5173. The ports differ, so it prints false.

One different part is enough. If only the path were different, the comparison would print true.

1function sameOrigin(a, b) {2  const left = new URL(a);3  const right = new URL(b);4  return left.origin === right.origin;5}

Watch for these cases. Each pair is a different origin:

• http and https: different schemes.
• www.example.com and example.com: different hosts.
• localhost:3000 and localhost:5173: different ports.
• localhost and 127.0.0.1: they reach the same computer, but the host text is different.

This lesson doesn't call any outside website. It can still make a real cross-origin request, safely.

The trick is an iframe: a small page inside this page. The iframe below is sandboxed, which means the browser limits what it may do. It has sandbox="allow-scripts" but not allow-same-origin. So the browser gives it a special origin that matches nothing. This is called an opaque origin, and the browser shows it as null. From inside the iframe, this site is a different origin.

1// Inside a sandboxed iframe with an opaque origin:2const target = "https://this-site.example";3 4async function corsMode() {5  try {6    const response = await fetch(target + "/javascript");7    return response.type + " " + response.status;8  } catch (error) {9    return error.name + ": " + error.message;10  }11}12 13async function noCorsMode() {14  const response = await fetch(target + "/javascript", { mode: "no-cors" });15  return response.type + " " + response.status;16}

Each button runs a different fetch inside the iframe:

• Normal fetch: this site's response has no Access-Control-Allow-Origin header for null. So the promise from fetch fails (it rejects) with a TypeError. The message text is different in each browser.
• Fetch with no-cors: the option mode: "no-cors" does not fix CORS. It gives JavaScript an opaque response: a response whose status, headers, and body are all hidden.
• Fetch a data: URL: a data: URL holds its text inside the URL itself. It is not a cross-origin request, so you can read it. Compare it with the other two.

function noCorsResult() {
  return { type: "opaque", status: 0, bodyReadable: false };
}

const response = noCorsResult();
console.log(response.type);
console.log(response.status);
console.log(response.bodyReadable);

This small model prints opaque, then 0, then false. The status is 0 and the body can't be read. So no-cors is not a way to read data from an API.

const serverReceivedRequest = true;
const browserCanReadResponse = false;

console.log(serverReceivedRequest);
console.log(browserCanReadResponse);

Line 4 prints true: the server got the request. Line 5 prints false: the browser did not let the page read the response. Both can be true at the same time.

CORS is a browser rule. A tool like curl, which sends requests from a terminal, doesn't check it. So when you debug, look in two places:

• The Network panel in the browser's DevTools, to see the request and the response headers.
• The server's logs, to see whether the request arrived.

function canBrowserRead(requestOrigin, responseHeaders) {
  return responseHeaders["Access-Control-Allow-Origin"] === requestOrigin;
}

console.log(canBrowserRead("https://app.example", { "Access-Control-Allow-Origin": "https://app.example" }));
console.log(canBrowserRead("https://app.example", { "Access-Control-Allow-Origin": "https://other.example" }));

canBrowserRead compares the page's origin with the response's Access-Control-Allow-Origin header.

• Line 5: the header names https://app.example, the same as the page. It prints true.
• Line 6: the header names https://other.example. It prints false.

This only models whether the page may read the response. The server got the request in both cases.

Some cross-origin requests are called simple requests. The browser sends them straight away. "Simple" is just an old name. It does not mean "safe". A request is simple when all of these are true:

• The method is GET, HEAD, or POST.
• Every request header is on a short allowed list. The spec calls these headers safelisted. Accept and Content-Type are on the list; Authorization and your own headers like X-Request-Id are not.
• If it sets Content-Type (the kind of data in the body), the value is one of these three: application/x-www-form-urlencoded, multipart/form-data, or text/plain.

Any other request needs a preflight: a check before the real request. The browser does it for you:

1. The browser sends an OPTIONS request. It asks: "May I send this method with these headers?" It names them in Access-Control-Request-Method and Access-Control-Request-Headers.
2. The server answers with what it allows.
3. If the answer is yes, the browser sends the real request. If not, it stops there.

const request = {
  method: "POST",
  headers: { "Content-Type": "application/json" },
};

const simpleMethods = ["GET", "HEAD", "POST"];
const simpleTypes = ["text/plain", "multipart/form-data", "application/x-www-form-urlencoded"];
const simple = simpleMethods.includes(request.method) && simpleTypes.includes(request.headers["Content-Type"]);

console.log(simple ? "send directly" : "preflight first");

The method is POST, which is on the simple list. But the Content-Type is application/json, which is not one of the three allowed values. So the code prints preflight first.

An Authorization header, or any header you make up, also needs a preflight. That is true even with GET.

function requestKind(method, headers = {}) {
  const simpleMethods = ["GET", "HEAD", "POST"];
  const contentType = headers["Content-Type"];
  const simpleTypes = ["text/plain", "multipart/form-data", "application/x-www-form-urlencoded"];
  const headersAreSafe = Object.keys(headers).every((name) => name === "Content-Type" && simpleTypes.includes(contentType));
  return simpleMethods.includes(method) && headersAreSafe ? "simple" : "preflight";
}

console.log(requestKind("GET"));
console.log(requestKind("PUT"));
console.log(requestKind("POST", { "Content-Type": "application/json" }));
console.log(requestKind("GET", { Authorization: "Bearer token" }));

• Line 9, a plain GET, prints simple.
• Line 10, a PUT, prints preflight: PUT is not a simple method.
• Line 11, a POST with JSON, prints preflight.
• Line 12, a GET with an Authorization header, prints preflight.

A common mistake is to look only at the method. The headers count too.

Now step through a full preflight. Pick an answer from the server, then step through the browser's checks.

1const request = {Run2  origin: "https://app.example",3  method: "PUT",4  headers: {5    "Content-Type": "application/json",6    "X-Request-Id": "abc123"7  },8  credentials: "include"9};10 11const response = {12  "Access-Control-Allow-Origin": "https://app.example",13  "Access-Control-Allow-Methods": "GET, POST, PUT",14  "Access-Control-Allow-Headers": "Content-Type, X-Request-Id",15  "Access-Control-Allow-Credentials": "true",16  "Vary": "Origin"17};18 19console.log(decideCors(request, response).verdict);

The permission is always in the response headers, which the server sends.

The main one is Access-Control-Allow-Origin. Its value can be one origin, such as https://app.example. Or it can be *, which means "any origin". * only works for requests without cookies; the Credentials section explains why.

For a preflight, the server also says which methods and which request headers it allows.

Each row below is one response header. The right column says what it tells the browser.

const responseHeaders = {
  "Content-Type": "application/json",
  "X-Request-Id": "abc123",
};

function canReadResponseHeader(name, exposedHeaders) {
  const safe = ["content-type", "cache-control"].includes(name.toLowerCase());
  const exposed = exposedHeaders.toLowerCase().split(",").map((item) => item.trim());
  return safe || exposed.includes(name.toLowerCase());
}

console.log(canReadResponseHeader("Content-Type", ""));
console.log(canReadResponseHeader("X-Request-Id", "X-Request-Id"));

Even when the page may read a response, it can't read every header on it.

• Line 12: Content-Type is on the short list of response headers JavaScript can always read. It prints true.
• Line 13: X-Request-Id is a custom header. It can be read only because the server named it in Access-Control-Expose-Headers: X-Request-Id. It prints true.

This permission is separate from the permission to read the response itself.

1const request = {2  origin: "https://app.example",3  url: "https://api.example/orders/7",4  method: "PUT",5  headers: { "Content-Type": "application/json", "X-Request-Id": "abc" },6  credentials: "include",7};8 9const response = {10  "Access-Control-Allow-Origin": "https://app.example",11  "Access-Control-Allow-Methods": "GET, POST, PUT",12  "Access-Control-Allow-Headers": "Content-Type, X-Request-Id",13  "Access-Control-Allow-Credentials": "true",14  "Access-Control-Max-Age": "600",15  "Vary": "Origin",16};17 18console.log(decideCors(request, response).verdict);

The simulator is plain JavaScript. It doesn't send any request. Change one setting at a time: the method, the content type, the custom header, cookies, or one of the server's headers. Then read the result.

Cookies and other credentials

Credentials are things that prove who you are to a server. There are three kinds:

• Cookies: small pieces of text a site saves in your browser, often to keep you signed in.
• HTTP authentication: a username and password the browser sends for you.
• Client certificates: digital ID files installed in the browser.

For a cross-origin request, fetch sends credentials only when you ask for them with credentials: "include". The Cookies lesson covers cookies in detail. Here, the CORS rule is what matters.

When a request includes credentials, the server must send two things:

• Access-Control-Allow-Credentials: true.
• The exact origin of the page in Access-Control-Allow-Origin. * is refused.

The browser refuses * here because it would let every site read your private, signed-in data.

A server often copies the page's origin into its answer, so the answer is different for each origin. Then it should also send Vary: Origin. A cache is a store of saved responses, kept to save time. Vary: Origin tells caches: "this answer depends on the origin, so don't give one origin's answer to another."

function canReadWithCredentials(origin, credentials, allowOrigin, allowCredentials) {
  if (credentials !== "include") return allowOrigin === "*" || allowOrigin === origin;
  return allowOrigin === origin && allowCredentials === "true";
}

console.log(canReadWithCredentials("https://app.example", "include", "*", "true"));
console.log(canReadWithCredentials("https://app.example", "include", "https://app.example", "true"));

Both calls send credentials ("include"). Both answers say credentials are allowed ("true").

• Line 6: the answer uses *. It prints false.
• Line 7: the answer names https://app.example. It prints true.

So an API that keeps users signed in with cookies, such as a profile API, must name the page's exact origin.

Where you will use this

You'll meet CORS in these places:

• On your own computer, while you build an app. http://localhost:3000 asking http://localhost:8080 is cross-origin, because the ports differ.
• On a live site. https://app.example asking https://api.example is cross-origin, because the hosts differ.
• When you use another company's service from the browser. That service must give your origin permission.

A proxy is a server that passes requests on to another server. During development, a dev proxy runs on the same origin as your page. Your page asks the proxy, and the proxy asks the API.

const frontend = "http://localhost:3000";
const api = "http://localhost:8080/orders";
const browserUrl = new URL("/api/orders", frontend);

console.log(browserUrl.origin === frontend);
console.log(new URL(api).origin === frontend);

• Line 5 prints true. The page calls /api/orders on its own origin, localhost:3000.
• Line 6 prints false. Calling the API on port 8080 directly would be cross-origin.

The proxy then sends the request on to the API. Server-to-server requests don't go through the browser's CORS check. A dev proxy only helps on your own computer. A live site still needs real CORS headers on the server, or the page and API on the same origin.

Common mistakes

• "CORS stops the request." A simple request is still sent, and the server can act on it. CORS stops the page from reading the response.
• "no-cors fixes it." It gives an opaque response. The status, headers, and body are all hidden.
• "The page can add Allow-Origin." Access-Control-Allow-Origin is a response header. Only the server can send it.
• "CORS protects against CSRF." CSRF is an attack where another site makes your browser send a request that changes something, like a payment. CORS doesn't stop that, because simple requests are still sent.
• "* works with cookies." A request with credentials needs the exact origin.

These five situations are easy to mix up. Each row says what happens and whether the page can read the response.

Key takeaways

• An origin is the scheme, host, and port. The path is not part of it.
• The same-origin policy stops a page from reading answers from another origin without permission.
• A simple cross-origin request is still sent. CORS decides whether the page may read the response.
• Other requests get a preflight: an OPTIONS check before the real request.
• Access-Control-Expose-Headers lets the page read extra response headers.
• With credentials, the server must name the exact origin and send Access-Control-Allow-Credentials: true.
• Fix CORS on the API server, a CDN, or a proxy. Page JavaScript can't give itself permission.

CORS is the browser checking a server's permission headers before it lets your JavaScript read an answer from another origin.

Up next: URL & URLSearchParams.