Chapter 42 — CORS: why the browser blocked your request

The thing to understand first

CORS is not server security. It restricts what browser JavaScript may read. curl, mobile apps, servers, and scripts ignore it entirely. Never use CORS to protect data — use authentication.

CORS exists to protect users from malicious websites, not to protect your API from attackers.

What an "origin" is

   https://app.example.com:443
   \___/   \_____________/ \_/
   scheme      host       port      -- ALL THREE must match

   https://app.example.com    vs  http://app.example.com     DIFFERENT (scheme)
   https://app.example.com    vs  https://api.example.com    DIFFERENT (host)
   https://app.example.com    vs  https://app.example.com:8443  DIFFERENT (port)

The two kinds of request

   SIMPLE REQUEST -- sent straight away
     * method is GET, HEAD, or POST
     * AND Content-Type is one of:
         text/plain, application/x-www-form-urlencoded, multipart/form-data
     * AND no custom headers

     -> browser SENDS it, then checks the response headers before letting
        your JavaScript READ the result.
        (Note: the request already happened. Side effects already occurred.)


   PREFLIGHTED REQUEST -- an extra round trip first
     * anything else: PUT, DELETE, PATCH
     * OR Content-Type: application/json          <-- this is the usual trigger
     * OR custom headers (Authorization, X-Api-Key, ...)

     -> browser first sends:
          OPTIONS /resource
          Origin: https://app.example.com
          Access-Control-Request-Method: PUT
          Access-Control-Request-Headers: content-type, authorization

     -> server must reply with matching permissions
     -> ONLY THEN does the real request go

Content-Type: application/json is what makes nearly every modern API call preflighted. That's why "my GET works but my POST doesn't" is the classic CORS complaint.

The headers the server must send

   Access-Control-Allow-Origin: https://app.example.com
   Access-Control-Allow-Methods: GET, POST, PUT, DELETE
   Access-Control-Allow-Headers: Content-Type, Authorization
   Access-Control-Allow-Credentials: true        (only if using cookies)
   Access-Control-Expose-Headers: X-Request-Id   (headers JS may READ)
   Access-Control-Max-Age: 86400                 (cache the preflight)
   Vary: Origin                                  (if you echo the origin back)

The four errors you will actually hit

1. Allow-Origin: * together with credentials. If the request sends cookies (credentials: 'include'), the wildcard is forbidden. You must echo the specific origin, add Access-Control-Allow-Credentials: true, and add Vary: Origin (or a cache will serve one origin's headers to another).

2. The preflight isn't handled. Your framework routes PUT /items but returns 404 or 405 for OPTIONS /items. The real request never happens. Handle OPTIONS explicitly.

3. A custom header isn't listed. You send X-Request-Id; the preflight response doesn't include it in Access-Control-Allow-Headers. Blocked.

4. You can't read a response header. By default JavaScript can only see a small safelist. Anything else needs Access-Control-Expose-Headers.

And one that wastes hours: an error response still needs CORS headers. If your server throws a 500 without them, the browser reports a CORS error, hiding the real failure. Add the headers in your error handler too.

curl -sI -X OPTIONS https://httpbin.org/anything \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: PUT' \
  -H 'Access-Control-Request-Headers: content-type' \
  | grep -iE 'access-control|^HTTP'

curl -sI https://httpbin.org/get -H 'Origin: https://app.example.com' \
  | grep -i access-control

// this will be BLOCKED by CORS (no permission headers from example.com)
fetch('https://example.com').then(r => r.text()).then(console.log).catch(console.error)

// this will WORK (httpbin sends Access-Control-Allow-Origin: *)
fetch('https://httpbin.org/get').then(r => r.json()).then(console.log)