Access-Control-* Header Directives

Without correct Access-Control-* response headers, every cross-origin fetch() or XMLHttpRequest either fails silently or triggers a browser console error — regardless of how well your application logic is written. A missing Access-Control-Allow-Origin, a mismatched credential flag, or an absent Vary: Origin can block entire API surfaces, leak cached responses to unintended origins, or prevent JavaScript from reading headers it legitimately needs.

This page is part of Server-Side CORS Configuration & Header Management, which covers the full server-side enforcement model. Here the focus is on the exact header semantics, browser-specific parsing rules, and the implementation patterns that hold up under production load.

Spec Anchor

The Access-Control-* response headers are defined in the WHATWG Fetch Standard, specifically the CORS protocol steps in §3.2. The algorithm describes how a browser validates each header field after a preflight OPTIONS exchange or a simple cross-origin response. Browser engines implement this spec independently, which is why Chrome, Firefox, and Safari differ on edge cases like Max-Age ceiling values and whitespace handling in header lists.

Preflight Flow: What the Browser Evaluates

Before understanding individual headers, it helps to see how they fit into the two-leg exchange the browser performs for non-simple requests.

Header Reference Table

Every Access-Control-* header operates in a specific phase — preflight response, actual response, or both. The table below maps each header to its phase, allowed values, browser-enforced limits, and whether it is required or optional.

Three parsing details are worth committing to memory, because each one produces a failure that looks like a server bug. Header names are compared case-insensitively, so access-control-allow-origin and Access-Control-Allow-Origin are the same header — but header values are not: Access-Control-Allow-Methods: post does not authorise a POST, because methods are compared as byte sequences and browsers send them uppercase. Second, the three CORS-safelisted methods (GET, HEAD, POST) pass the preflight method check even when Access-Control-Allow-Methods omits them, which is why a policy listing only PUT still lets a GET through and hides an incomplete configuration until someone adds a PATCH. Third, Chromium normalises Access-Control-Request-Headers to lowercase and sorts it alphabetically before sending, so the string in DevTools rarely matches the casing in your client code — compare sets, not strings.

Step-by-Step Implementation

1. Identify the preflight trigger

A preflight OPTIONS request fires when any of these conditions are true:

• The method is not GET, HEAD, or POST.
• POST is used with a Content-Type other than application/x-www-form-urlencoded, multipart/form-data, or text/plain.
• Any header outside the CORS-safelisted set is present (e.g. Authorization, X-Custom-Header).
• A ReadableStream body is attached to the request.

The browser sends Access-Control-Request-Method and Access-Control-Request-Headers in the preflight so the server knows exactly what capability it is authorising.

2. Respond to the preflight (Nginx)

# nginx.conf — CORS preflight and response headers
map $http_origin $cors_origin {
    default                        "";
    "https://app.example.com"      "https://app.example.com";
    "https://dashboard.example.com" "https://dashboard.example.com";
}

server {
    listen 443 ssl;
    server_name api.example.com;

    location /v1/ {
        # Preflight fast-path
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin'  $cors_origin always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, PATCH, OPTIONS' always;
            add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-Request-Id' always;
            add_header 'Access-Control-Max-Age'       '600' always;
            add_header 'Access-Control-Allow-Credentials' 'true' always;
            add_header 'Vary'                         'Origin' always;
            return 204;
        }

        # Actual request headers
        add_header 'Access-Control-Allow-Origin'       $cors_origin always;
        add_header 'Access-Control-Allow-Credentials'  'true' always;
        add_header 'Access-Control-Expose-Headers'     'X-Request-Id, X-RateLimit-Remaining' always;
        add_header 'Vary'                              'Origin' always;

        proxy_pass http://backend;
    }
}

The always flag ensures headers are appended even on 4xx/5xx responses, where browsers still enforce CORS before exposing error details to JavaScript.

3. Respond to the preflight (Express/Node.js)

// cors-middleware.js
const ALLOWED_ORIGINS = new Set([
  'https://app.example.com',
  'https://dashboard.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, PATCH, OPTIONS');
    res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, X-Request-Id');
    res.setHeader('Access-Control-Max-Age', '600');
    return res.sendStatus(204);
  }

  // Expose non-safelisted headers on actual responses
  res.setHeader('Access-Control-Expose-Headers', 'X-Request-Id, X-RateLimit-Remaining');
  next();
}

module.exports = corsMiddleware;

Safe origin reflection — where the server only echoes the Origin value when it is on the allowlist — is the correct alternative to a wildcard for credentialed requests. See Dynamic Origin Validation Patterns for production-grade allowlist management, including regex guards and subdomain normalization.

4. Return the actual response with expose headers

On the actual (non-preflight) response, Access-Control-Allow-Methods and Access-Control-Allow-Headers have no effect. The browser only reads Access-Control-Allow-Origin, Access-Control-Allow-Credentials, and Access-Control-Expose-Headers from the actual response. Sending the full set on the actual response is harmless but add-headers-on-actual-response should always include Vary: Origin.

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: X-Request-Id, X-RateLimit-Remaining
Vary: Origin
Content-Type: application/json

Without Access-Control-Expose-Headers, only the seven CORS-safelisted response headers (Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified, Pragma) are readable by response.headers.get() in JavaScript. Custom telemetry headers like X-Request-Id are silently hidden.

Two exposure rules trip people up. Set-Cookie and Set-Cookie2 are forbidden response header names: naming them in Access-Control-Expose-Headers has no effect, because the browser never lets script read them from any response, same-origin or not. And Content-Length is already safelisted, so a client that cannot read it is failing for a different reason — usually because the response was fetched in no-cors mode and is opaque.

5. Keep the headers on error responses

CORS is evaluated before the browser hands a response to script, and that check does not care about the status code. A 401, 429 or 500 that arrives without Access-Control-Allow-Origin is blocked exactly like a missing header on a 200, so the JavaScript catch block sees a generic network error rather than the status you sent. That is why the Nginx snippet above uses always on every add_header: without it, Nginx only emits the header on 200, 201, 204, 301, 302 and 304, and every genuine error becomes an unreadable CORS failure. In Express, register the CORS middleware before the router and make sure the error handler does not construct a fresh response object that skips it.

// Error handler must not lose the CORS headers set upstream.
app.use((err, req, res, next) => {
  const origin = req.headers['origin'];
  if (origin && ALLOWED_ORIGINS.has(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Vary', 'Origin');
  }
  res.status(err.status || 500).json({ error: err.code || 'internal_error' });
});

6. Answer the private-network preflight where it applies

Chromium sends an extra preflight field, Access-Control-Request-Private-Network: true, when a page on a public origin requests a resource on a private or loopback address — a dashboard on https://app.example.com calling http://192.168.1.10/api, or a hosted page calling http://localhost:8080. The preflight only succeeds if the response carries Access-Control-Allow-Private-Network: true alongside the usual Access-Control-Allow-Origin. Firefox and Safari do not send the field, so the same deployment works in one browser and fails in another with no configuration difference — a symptom often misread as a caching problem. If your product embeds a local agent or a device on the LAN, add the header on that device’s OPTIONS responder rather than loosening the public API.

Edge Cases and Security Boundaries

Null origin and sandboxed iframes

Requests from sandboxed <iframe> elements without allow-same-origin, data URIs, and some local file schemes send Origin: null. Never allowlist null as a trusted origin — it is a synthetic value shared by many unrelated contexts. A server that reflects Access-Control-Allow-Origin: null with credentials enabled exposes its API to any sandboxed page an attacker constructs.

Subdomain mismatch

https://api.example.com and https://app.example.com are distinct origins. A server that allowlists only https://example.com will reject requests from its own subdomains. Conversely, a regex that matches *.example.com without anchoring will accept https://evil-example.com — ensure your pattern is anchored and requires a dot before the root domain.

Opaque responses and no-cors mode

fetch() in no-cors mode returns an opaque response — the browser blocks access to headers, body, and status regardless of server-side CORS headers. This mode is for fire-and-forget side-effect requests (like beacon pings) where the response is intentionally unreadable.

Wildcard with credentials

The Fetch Standard §3.2.3 states: if credentials is include and Access-Control-Allow-Origin is *, the browser must return a network error. The same applies to Access-Control-Allow-Headers: * and Access-Control-Expose-Headers: * — in credentialed contexts, * is treated as a literal header name, not a wildcard, causing silent header allowlist failures. See Wildcard Risks & Mitigation for the full security boundary analysis.

The asterisk therefore means two entirely different things depending on the credentials mode, one column of this matrix per mode:

Browser parsing: trailing commas and whitespace

Blink and WebKit engines trim whitespace around comma-separated values but treat trailing commas as an empty final entry. A value of Content-Type, Authorization, (trailing comma) may cause silent rejection of Authorization on some browser versions. Validate your header values with the curl verification checklist below before deploying.

Proxy and CDN Interaction

Missing Vary: Origin poisons the cache

CDN edge nodes cache the first Access-Control-Allow-Origin response they receive and serve it to every subsequent request for that URL — regardless of the actual Origin header on the inbound request. If the first cached response contains Access-Control-Allow-Origin: https://app.example.com, all users from https://dashboard.example.com receive a mismatched origin and are blocked. Adding Vary: Origin instructs the CDN to maintain a separate cache entry per distinct origin value.

For deeper coverage of how Vary interacts with CDN caching layers, see Handling Vary: Origin Header Correctly.

Access-Control-Max-Age and browser cache

The preflight cache is browser-side, not CDN-side. Access-Control-Max-Age: 600 tells the browser to skip the preflight OPTIONS round-trip for up to 600 seconds for the same URL, method, and header combination. The CDN never sees the cached preflights — they happen locally in the browser’s preflight cache. This means high Max-Age values mask server-side header changes during debugging, even after a CDN purge.

Plotted against the clock, one cache entry has a single warm window and a hard edge at its end:

Framework defaults worth auditing

Most production incidents in this area come from a library’s default rather than from a hand-written header. Four defaults are worth checking before you debug anything else. The Express cors package treats origin: true as “reflect whatever arrived”, which is an allowlist that allows everything — pass a function or an array instead, and note that the package only adds Vary: Origin when the origin option is dynamic. Spring’s @CrossOrigin annotation defaults maxAge to 1800 seconds, a value Chromium silently clamps to 600, so the annotation and the observed behaviour disagree by a factor of three. django-cors-headers keeps credentials off until you set CORS_ALLOW_CREDENTIALS = True, which is separate from the origin allowlist and easy to miss during a migration. And AWS API Gateway’s REST APIs answer OPTIONS from a MOCK integration with static header values, so a multi-origin allowlist has to be expressed in the integration response mapping or moved into a Lambda authorizer — the console’s “Enable CORS” button generates the wildcard version, which is incompatible with credentials. The same reflection-versus-allowlist decision is examined in depth in dynamic origin validation patterns.

Reverse-proxy header stripping

Reverse proxies (HAProxy, Nginx upstream, AWS ALB) sometimes strip or rewrite Access-Control-* headers set by the origin server — particularly if the proxy itself adds a conflicting Access-Control-Allow-Origin. Duplicate header injection results in a multi-value header (https://app.example.com, https://app.example.com) which browsers treat as invalid. Audit your proxy configuration to ensure headers are set in exactly one place.

DevTools + curl Verification Checklist

• Send a synthetic preflight and confirm 200 or 204 status with correct Access-Control-Allow-Origin:

  curl -i -X OPTIONS \
    -H "Origin: https://app.example.com" \
    -H "Access-Control-Request-Method: POST" \
    -H "Access-Control-Request-Headers: Authorization, Content-Type" \
    https://api.example.com/v1/resource

• Confirm Access-Control-Allow-Credentials: true appears in the preflight response (if credentials are required).
• Confirm Vary: Origin appears in both the preflight and actual response headers.
• Open DevTools → Network, filter by the request URL, check the Response Headers panel for every Access-Control-* header.
• In the DevTools Console, confirm no CORS error message appears after the actual request completes.
• Test with a second origin (e.g. https://dashboard.example.com) to confirm the CDN returns a separate cache entry with the correct reflected origin.
• Set Access-Control-Max-Age: 0 temporarily, reload, and confirm a fresh preflight fires every time — then restore to 600.
• Verify Access-Control-Expose-Headers includes every custom header your frontend reads via response.headers.get().
• Confirm that an unlisted origin (e.g. https://evil.example.com) receives an empty Access-Control-Allow-Origin and the browser blocks the response.

Common Mistakes

FAQ