CORS Internals & Preflight

Why Your Fetch Fails (And Why That's a Feature)

You've hit a CORS error. The response was 200 OK. The data was right there in the network tab. But the browser refused to let your JavaScript read it. This feels broken — but it's actually the browser protecting your users.

Here's what most developers get wrong: CORS errors don't come from the server rejecting your request. The server handled it fine. The browser blocked your JavaScript from reading the response because the server didn't explicitly say "yes, this origin is allowed to see my data."

The Same-Origin Policy: Why CORS Exists

Before CORS, the Same-Origin Policy (SOP) was the only access control. It's simple: JavaScript on https://myapp.com can only read responses from https://myapp.com. Any other origin is blocked.

An "origin" is the combination of scheme + host + port:

https://myapp.com:443   → origin: https://myapp.com
http://myapp.com:80     → different origin (http vs https)
https://api.myapp.com   → different origin (different host)
https://myapp.com:8080  → different origin (different port)

SOP prevents a malicious page from reading your bank's API responses while you're logged in. Without it, any website you visit could make authenticated requests to your bank (your cookies go along for the ride) and read the account data.

CORS is the opt-in mechanism that lets servers relax this restriction: "I know this request is cross-origin, and I'm okay with that specific origin reading my response."

Simple Requests vs Preflight Requests

Not all cross-origin requests are treated equally. The browser divides them into two categories based on what you're asking to do.

Simple Requests

A request is "simple" (the spec calls it a "CORS-safelisted request") if it meets ALL of these conditions:

• Method: GET, HEAD, or POST only
• Headers: Only Accept, Accept-Language, Content-Language, Content-Type, Range
• Content-Type (if present): Only application/x-www-form-urlencoded, multipart/form-data, or text/plain
• No ReadableStream body
• No event listeners on XMLHttpRequest.upload

Simple requests go directly to the server. The browser sends the request, checks the response headers, and decides whether to expose the response to JavaScript.

GET /api/public HTTP/1.1
Host: api.example.com
Origin: https://myapp.com

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://myapp.com
Content-Type: application/json

{"data": "public info"}

Preflight Requests

Anything that doesn't qualify as "simple" triggers a preflight — an OPTIONS request the browser sends before the actual request. This is the browser asking: "Hey server, would you accept this kind of request from this origin?"

Common triggers for preflight:

• Method is PUT, PATCH, or DELETE
• Custom headers like Authorization, X-Request-ID
• Content-Type is application/json
• Request includes credentials in certain configurations

OPTIONS /api/users HTTP/1.1
Host: api.example.com
Origin: https://myapp.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: Content-Type, Authorization

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://myapp.com
Access-Control-Allow-Methods: GET, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

If the preflight passes, the browser sends the actual PUT request. If it fails, the actual request never leaves the browser.

Every Access-Control Header Explained

Request Headers (sent by the browser)

Response Headers (sent by the server)

The Expose-Headers Gotcha

By default, JavaScript can only read these response headers: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Pragma. Everything else is hidden unless the server explicitly exposes it:

Access-Control-Expose-Headers: X-Total-Count, X-Request-ID

This catches a lot of developers off guard. Your API returns a custom header, you can see it in DevTools, but response.headers.get('X-Total-Count') returns null. The header is there — the browser just won't let your JS read it without explicit permission.

Credentials Mode: Cookies and Cross-Origin

By default, cross-origin fetch requests don't send cookies. This is a deliberate security choice — you don't want every random website sending your bank's session cookie along with its requests.

To send cookies cross-origin, both sides must opt in:

Client side:

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

Server side:

Access-Control-Allow-Origin: https://myapp.com   // MUST be specific, NOT *
Access-Control-Allow-Credentials: true

The Three Credentials Modes

// "omit" — never send cookies (even same-origin)
fetch(url, { credentials: 'omit' })

// "same-origin" — send cookies only for same-origin requests (default)
fetch(url, { credentials: 'same-origin' })

// "include" — send cookies for all requests, including cross-origin
fetch(url, { credentials: 'include' })

Preflight Caching: The Performance Angle

Every preflight request adds latency — it's an extra round trip before the actual request. The Access-Control-Max-Age header tells the browser to cache the preflight result:

Access-Control-Max-Age: 86400  // cache for 24 hours

Without this header, browsers use their own defaults (Chrome caches for 2 hours, Firefox for 24 hours). Set it explicitly to avoid per-browser surprises.

The cache key is (origin, URL, credentials mode). A request from a different origin or with different credentials triggers a fresh preflight even if the same URL was preflighted before.

Production Scenario: Configuring CORS for a Multi-Tenant API

Your API serves multiple frontend apps across different domains. Here's a production-grade CORS configuration pattern in Node.js:

const ALLOWED_ORIGINS = new Set([
  'https://app.example.com',
  'https://admin.example.com',
  'https://staging.example.com',
])

function corsMiddleware(req, res, next) {
  const origin = req.headers.origin

  if (origin && ALLOWED_ORIGINS.has(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin)
    res.setHeader('Access-Control-Allow-Credentials', 'true')
    res.setHeader('Vary', 'Origin')
  }

  if (req.method === 'OPTIONS') {
    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE')
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')
    res.setHeader('Access-Control-Max-Age', '86400')
    res.writeHead(204)
    res.end()
    return
  }

  next()
}

Key details:

• Explicit origin allowlist — no wildcard, no reflected origin
• Vary: Origin — critical for CDN/proxy caches. Without it, a cached response with Allow-Origin: https://app.example.com might be served to admin.example.com, breaking CORS
• 204 for OPTIONS — no body needed for preflight responses
• Max-Age: 86400 — reduces preflight overhead for repeated requests

Challenge: Debug This CORS Configuration

app.use((req, res, next) => {
  const origin = req.headers.origin
  if (origin && origin.endsWith('.example.com')) {
    res.setHeader('Access-Control-Allow-Origin', origin)
  }
  res.setHeader('Access-Control-Allow-Credentials', 'true')
  res.setHeader('Access-Control-Allow-Methods', '*')
  res.setHeader('Access-Control-Allow-Headers', '*')
  next()
})