CORS preflight simulator

Start from a scenario, then change one thing at a time. The first row of settings is the request the page makes with fetch(): its method, its Content-Type, whether it sends an Authorization or X-Api-Key header, and whether it includes cookies (credentials: 'include'). The second row is what the API server sends back. The middle panel shows each HTTP message with its headers, and the panel on the right says whether the page gets the response and why.

Things to try:

• From JSON POST, set Content-Type to text/plain: the preflight disappears, because a form could send that.
• From API with a token, add Authorization to Allow-Headers, then DELETE to Allow-Methods.
• Pick Cookies and *, then switch Allow-Origin to app.example.com.
• Make a simple GET fail, and notice that the request still reached the server.

An origin is the scheme, host and port of a URL: https://app.example.com and https://api.example.net are different origins, and so are http:// and https:// versions of the same host, or two ports. Browsers apply the same-origin policy: a page may send requests to other origins, but its scripts may not read the responses. Without it, any website you visit could read your email or bank pages using the cookies your browser holds for them.

Cross-Origin Resource Sharing (CORS) is the controlled exception. A server that wants its responses to be readable by pages on other origins says so in response headers, starting with Access-Control-Allow-Origin. The browser checks those headers before passing the response to script. For requests that could do something an ordinary web page could not already do, the browser first asks permission with a preflight request.

HTML forms have always been able to send GET and POST requests to any site, with a few kinds of body. CORS keeps that behaviour unchanged: requests that a form could send go straight to the server, and only the response is checked. These are often called simple requests. A request is simple when:

• its method is GET, HEAD or POST, and
• every header the page sets is on the safelist: Accept, Accept-Language, Content-Language, and Content-Type with one of application/x-www-form-urlencoded, multipart/form-data or text/plain.

Anything else gets a preflight: PUT, PATCH and DELETE; a JSON body (Content-Type: application/json); an Authorization header; any custom header such as X-Api-Key or X-Requested-With. Headers the browser adds itself, such as Origin, User-Agent or cookies, do not count.

The preflight is an OPTIONS request to the same URL, without a body or cookies, carrying three headers: Origin, Access-Control-Request-Method with the method of the real request, and Access-Control-Request-Headers with the names of the non-safelisted headers, lower-cased, sorted and separated by commas. The server answers with what it allows:

Cross-origin fetch() does not send cookies unless the page asks with credentials: 'include' (or withCredentials = true with XMLHttpRequest). When it does, the rules tighten: the response must name the exact origin in Access-Control-Allow-Origin, include Access-Control-Allow-Credentials: true, and the * wildcard stops working in every CORS header.

A server that allows several origins therefore reads the request’s Origin header, checks it against an allowlist and echoes it back. When the header’s value depends on the request, the server should also send Vary: Origin, so that caches do not serve a response meant for one origin to another. Never echo the Origin without checking it: that is equivalent to allowing every site to read authenticated responses.

Even when the request succeeds, script on another origin can only read the CORS-safelisted response headers: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified and Pragma. Other headers, such as a request ID, a rate-limit counter or Location, are invisible to response.headers.get() unless the server lists them in Access-Control-Expose-Headers. In the simulator, toggle Expose X-Request-Id and watch it move from hidden to readable.

A preflight costs a full round trip before every non-simple request, so browsers cache successful preflight answers. Access-Control-Max-Age sets how long, in seconds. Without it the Fetch Standard’s default is 5 seconds, and browsers cap long values: Chromium at 7,200 seconds (two hours) and Firefox at 86,400 (24 hours). The cache entry is specific to the origin, the URL, and the method or header that was allowed, so APIs with many distinct URLs, such as /orders/42 and /orders/43, still pay for a preflight on each URL. Avoiding preflights altogether, by serving the API from the same origin as the page (for example under /api behind the same domain), removes the round trip entirely.

Each row starts from the JSON POST scenario and changes one thing. The reason is the one the simulator gives, which matches what the browser console reports in other words.

CORS is a browser feature that decides whether a page may read a response. It is not access control for the server. A simple request reaches the server and is handled before the browser looks at any CORS header; the browser only hides the answer. Requests from curl, a mobile app or another server ignore CORS completely. And a page can still embed images, scripts and stylesheets from other origins, and submit forms to them, without CORS.

So a state-changing endpoint needs its own protection against cross-site request forgery: SameSite cookies, CSRF tokens, or requiring a header that forces a preflight (such as a JSON content type or a custom header) and rejecting requests without it. Authentication and authorisation are still the server’s job.

The rules in the simulator follow the Fetch Standard. To check them, the same model was compared with Chromium 141: a test page on one origin made fetch() calls to a small server on another origin, over 500 random combinations of method, headers, credentials and server CORS headers. For each one we compared whether a preflight was sent, the exact Access-Control-Request-Headers value, whether the real request reached the server, whether fetch() succeeded, and which response headers script could read. All 500 matched.

One difference from the standard turned up. The standard says Access-Control-Allow-Headers: * does not cover Authorization, which must always be listed by name. Chromium 141 accepted it under the wildcard. The simulator follows the standard and notes the difference; to work in every browser, list Authorization explicitly.

Frontend and full-stack interviews often ask what CORS is, why a request to an API works in curl but fails in the browser, and why a POST turns into an OPTIONS request. A good answer explains the same-origin policy, the difference between simple and preflighted requests, the headers involved, and the credentials rule about *, and makes clear that CORS protects users’ data in the browser rather than protecting the server.

In system design, CORS comes up when a frontend and an API live on different domains. Serving both from one origin, or terminating CORS once in an API gateway rather than in every service, are common answers.