Security · Lesson 04

CORS, explained

Every frontend developer has hit a CORS error. Most fix it by cargo-culting headers until it stops. This lesson explains what is actually happening — why the browser enforces it, what CORS headers mean, and the one mistake that secretly undoes the protection.

The threat the Same-Origin Policy is designed to limit

Imagine you are logged in to your bank at bank.example.com. You open a second tab and visit evil.example.com. That page's JavaScript runs fetch("https://bank.example.com/v1/accounts/me", { credentials: "include" }). Your browser automatically attaches your bank session cookie — you are authenticated. Without any protection, the bank response (balances, account numbers) would be readable by evil.com's script.

The Same-Origin Policy (SOP) is the browser's primary defence against cross-origin response reading: by default, a script on one origin may not read the response of a request to a different origin — even when cookies were sent. Closely related but distinct: Cross-Site Request Forgery (CSRF) is about forging a state-changing request (transfer money, change email) that the browser still sends with cookies. SOP/CORS do not fully stop CSRF for simple requests; you need SameSite cookies, CSRF tokens, or non-cookie auth for that.

What is an "origin"?

An origin is the exact combination of scheme + hostname + port. All three must match for two URLs to share an origin:

The SOP means a page at https://frontend.example.com and an API at https://api.example.com are cross-origin — even though they share the same second-level domain. Without CORS, the browser will block the frontend from reading the API's response.

CORS — controlled relaxation of the SOP

CORS (Cross-Origin Resource Sharing) is an HTTP header protocol that lets the API server tell the browser: "I permit requests from this origin." It is not a way to bypass security — it is a precise, opt-in mechanism to declare which cross-origin callers are trusted.

The five headers you need to know:

The preflight request

For "non-simple" requests (anything other than a GET/HEAD/POST with plain form content-type, or any request with custom headers like Authorization), the browser sends an automatic OPTIONS request first — the preflight. This asks the server: "Would you accept the real request I am about to send?" Only if the server's CORS headers say yes does the browser proceed with the actual request.

# A correctly configured CORS preflight response
HTTP/1.1 204 No Content
Access-Control-Allow-Origin:  https://frontend.example.com
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Request-ID
Access-Control-Allow-Credentials: true
Access-Control-Max-Age:       86400

# The actual POST response must also repeat the Allow-Origin header:
HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: https://frontend.example.com

CORS is enforced by the browser, not the server

This is the single most-misunderstood fact about CORS. The server sends headers expressing its policy. The browser reads those headers and decides whether to expose the response to the JavaScript. A server with no CORS headers will still receive and process every request — it just won't tell the browser the response is safe to share with cross-origin scripts.

What this means in practice: CORS does nothing to protect your API from curl, Postman, a mobile app, a server-side script, or any non-browser client. Those tools ignore CORS headers entirely. CORS protects browser users from being used as unwitting request-makers on a malicious page — it does not protect the API itself from direct calls.

Under the hood: simple vs preflighted requests

The browser splits cross-origin requests into two categories, and the rules for which is which are exact — not vibes. A request is "simple" (no preflight) only if it meets all of these conditions:

• Method is GET, HEAD, or POST.
• The only headers your code set are on the CORS "safelist" (Accept, Accept-Language, Content-Language, Content-Type, plus a couple more).
• Content-Type, if present, is one of application/x-www-form-urlencoded, multipart/form-data, or text/plain.

Break any of those and the request becomes "preflighted". In practice almost every real API call is preflighted, because two extremely common things both trip it: sending Authorization: Bearer … (a non-safelisted header) and sending Content-Type: application/json (not on the safelisted content-type list). That single JSON header is why your innocent-looking fetch suddenly fires an OPTIONS first.

How to debug & inspect it

Three facts make CORS debugging fast once you internalise them: (1) the error is always in the browser console, never your server logs; (2) the fix is always a response header from your server; (3) curl and Postman will happily succeed on the same URL because they don't enforce CORS — so "works in curl, fails in browser" is the classic signature, not a contradiction.

Reproduce the preflight yourself with curl by sending the OPTIONS the browser would send, and read what comes back:

In DevTools: open Network, find the OPTIONS row (the preflight) sitting just before your real call; inspect its response headers. The failed real request shows status (blocked:cors). Map the red console message to its cause:

Debug checklist:

1. Confirm it's actually CORS: is the error in the console and does the same URL succeed in curl? If yes → CORS, not your server logic.
2. In Network, is there an OPTIONS preflight? Open it and read the response headers.
3. Compare the request's Origin, method, and headers against the server's Allow-Origin/Allow-Methods/Allow-Headers — find the mismatch.
4. If credentials are involved, verify Allow-Origin is a specific origin (not *) and Allow-Credentials: true is present.
5. Add Vary: Origin if you echo the origin, so a CDN doesn't cache one origin's ACAO and serve it to another.

By the numbers

Let's calculate the latency penalty, request amplification, and API Gateway billing costs generated by CORS preflight OPTIONS requests. Consider a client on a mobile network with 120 ms RTT (Round Trip Time) calling a JSON API. The API processes requests in 40 ms. Our website receives 5,000 cross-origin requests/sec (QPS) from a population of 1,000,000 active unique clients. We compare the metrics with and without preflight caching.

Governing Formulas

The total latency for a preflighted request $L_{\text{preflighted}}$ (when the cache is empty or missing) is:

When the preflight result is cached in the browser ($L_{\text{cached}}$):

The monthly request volume $V_{\text{monthly}}$ without caching is:

The monthly request volume with preflight caching ($V_{\text{cached\_monthly}}$) over $U$ unique users refetching every $H$ hours is:

Step-by-Step Scenario Analysis

Let's trace the network exchanges and latencies for a client making two sequential API calls under different configurations:

Decision Math: Sizing the Financial Savings

Let's calculate the API Gateway billing overhead at a peak load of 5,000 QPS over a 30-day month (assuming AWS API Gateway HTTP API pricing of $1.00 per million requests, and REST API pricing of $3.50 per million):

• Requests without cache: $5,000 \text{ QPS} \times 86,400 \text{ s/day} \times 30 \text{ days} \times 2 = \mathbf{25.92\text{ billion requests}}$.
• Requests with cache (1M clients, cached 24h): $12.96\text{B (POSTs)} + (1\text{M} \times 30\text{ days} \times 1\text{ OPTIONS}) = \mathbf{12.99\text{ billion requests}}$.
• Monthly request volume saved: $25.92\text{B} - 12.99\text{B} = \mathbf{12.93\text{ billion requests}}$ (a 50% reduction).
• Monthly Billing Savings:
  • HTTP API: $12,930\text{ million} \times \$1.00 = \mathbf{\$12,930\text{ per month}}$.
  • REST API: $12,930\text{ million} \times \$3.50 = \mathbf{\$45,255\text{ per month}}$ saved in raw network bills by setting one single header: Access-Control-Max-Age: 86400.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true

# Corrected configuration
Access-Control-Allow-Origin:      https://dashboard.company.com
Access-Control-Allow-Methods:     GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers:     Content-Type, Authorization
Access-Control-Allow-Credentials: true
Access-Control-Max-Age:           86400

Sources & further reading

• MDN — Cross-Origin Resource Sharing (CORS)
• MDN — Same-Origin Policy
• WHATWG Fetch Standard — CORS protocol