Catalog My learning Blog
Browser Security Headers: CORS, CSP and Cookies Explained · Phase 2 · Lesson 9 · 6 min read

CORS Headers Explained: Access-Control-Allow-Origin

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: A Correct Multi-Origin CORS Implementation
  4. Real-World Examples
  5. Review Questions & Answers

Learning Objective

Describe precisely what each CORS response header controls, including the often-overlooked Access-Control-Expose-Headers, and explain which headers apply to the preflight, which to the actual response, and which to both.

Concept Explanation

There are six CORS response headers and they divide cleanly by where they apply. Access-Control-Allow-Origin applies to both the preflight and the actual response and must be present on both; forgetting it on the actual response after correctly answering the preflight is a common and confusing bug. Access-Control-Allow-Credentials also applies to both. Access-Control-Allow-Methods, Access-Control-Allow-Headers, and Access-Control-Max-Age apply only to the preflight and are ignored on an actual response. Access-Control-Expose-Headers applies only to the actual response and is meaningless on a preflight.

Access-Control-Allow-Origin takes exactly one value: a single serialized origin, or the wildcard. It is not a list. A server that needs to support several origins must inspect the incoming Origin header, decide whether it is on its own allowlist, and echo that single value back, which is why dynamic reflection is so common and why the next lesson is devoted to the ways it goes wrong. The null value is also possible, and is specifically hazardous because sandboxed iframes, some redirect chains, and data URLs all present a null origin, so allowing null effectively allows any attacker willing to put their payload in a sandboxed frame.

Access-Control-Expose-Headers is the header most teams discover late and by accident. By default, script reading a cross-origin response can see only a small safelist of response headers: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified, and Pragma. Everything else, a pagination header, a rate limit header, a request id used for support tickets, a Location header after a create, is invisible to the calling script even though the response contains it and the browser received it. Naming those headers in Access-Control-Expose-Headers is what makes them readable, and its absence produces the classic "the header is right there in the network tab but my code sees undefined."

Access-Control-Allow-Methods and Access-Control-Allow-Headers each accept a comma-separated list, and each accepts a wildcard, but the wildcard only works for requests without credentials. When Access-Control-Allow-Credentials is true, the wildcard loses its special meaning in all of these headers and is treated as the literal string asterisk, which will match no real method or header name. This is a deliberate spec decision that prevents a server from accidentally granting blanket credentialed access, and it is why a policy that works for public endpoints suddenly stops working the moment credentials are added.

One more subtlety worth knowing: Access-Control-Allow-Headers must cover every non-safelisted header the client will send, and the matching is case-insensitive but the coverage must be complete. If the client sends Authorization, Content-Type, and X-Request-Id, and the server approves only the first two, the entire preflight fails; there is no partial approval in which the third header is simply dropped. Libraries that add a tracing or correlation header automatically are a frequent cause of a preflight that used to pass and now does not.

HeaderApplies toValueControls
Access-Control-Allow-OriginPreflight and actual responseOne origin, or a wildcard, or nullWhether script on that origin may read the response
Access-Control-Allow-CredentialsPreflight and actual responseThe literal string true, or absentWhether cookies and auth may be sent and the response read
Access-Control-Allow-MethodsPreflight onlyComma-separated method list, or a wildcardWhich methods the real request may use
Access-Control-Allow-HeadersPreflight onlyComma-separated header list, or a wildcardWhich non-safelisted request headers are permitted
Access-Control-Max-AgePreflight onlySeconds, clamped by the browserHow long the preflight result may be cached
Access-Control-Expose-HeadersActual response onlyComma-separated header list, or a wildcardWhich response headers script is allowed to read

Worked Example: A Correct Multi-Origin CORS Implementation

The implementation below handles the three things a hand-written CORS layer most often gets wrong: an exact allowlist rather than a pattern match, Vary: Origin so caches key correctly, and exposing the specific headers the front end actually needs to read.

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

app.use((req, res, next) => {
  const origin = req.headers.origin;

  // Always vary on Origin, even when we do not allow this one, so that a
  // shared cache never serves one origin's decision to another.
  res.setHeader('Vary', 'Origin');

  if (origin && ALLOWED_ORIGINS.has(origin)) {   // exact match, no regex
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Access-Control-Allow-Credentials', 'true');
    // Without this line, script sees undefined for these headers even
    // though the browser received them.
    res.setHeader('Access-Control-Expose-Headers',
      'X-Request-Id, X-Total-Count, X-RateLimit-Remaining');
  }

  if (req.method === 'OPTIONS') {
    if (!origin || !ALLOWED_ORIGINS.has(origin)) return res.status(403).end();
    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE');
    res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, X-Request-Id');
    res.setHeader('Access-Control-Max-Age', '7200');
    return res.status(204).end();   // answered BEFORE any auth middleware
  }

  next();
});
The six CORS response headers arranged by where they apply, preflight only, actual response only, or both, with the request-side header each one answers shown alongside.
The six CORS response headers arranged by where they apply, preflight only, actual response only, or both, with the request-side header each one answers shown alongside.

Real-World Examples

  • The wildcard losing its meaning when credentials are enabled is specified in the WHATWG Fetch Standard and implemented uniformly across browsers, which is why teams routinely report that a CORS configuration working fine for a public API breaks the moment they add cookie authentication; the fix is not a browser workaround but echoing a specific allowlisted origin, because the specification deliberately forbids combining blanket permission with ambient credentials.
  • Access-Control-Expose-Headers is the reason rate-limit headers from public APIs such as GitHub's X-RateLimit-Remaining are readable from browser clients at all: an API that returns operational headers but does not expose them leaves browser consumers unable to read values that are plainly visible in developer tools, a mismatch that generates a steady stream of confused issue reports against API client libraries.
Key TakeawaysAccess-Control-Allow-Origin takes a single value, not a list, and must appear on the actual response as well as the preflight. If you compute it from the request, always send Vary: Origin, and remember that any response header beyond the seven-item safelist is invisible to script unless you name it in Access-Control-Expose-Headers.

Review Questions & Answers

Access-Control-Expose-Headers on the actual response. By default, script reading a cross-origin response may access only the seven safelisted response headers: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified, and Pragma. The browser received X-Request-Id and shows it in developer tools, but it will not expose it to script until the server explicitly names it, which is a read permission distinct from the one granted by Access-Control-Allow-Origin.

The Fetch Standard removes the wildcard's special meaning entirely for credentialed requests, in every CORS header that accepts one, and treats it as the literal character. The rule prevents a server from accidentally granting blanket permission for requests carrying a user's ambient credentials, since that combination is precisely the dangerous one. A credentialed policy must therefore enumerate its allowed origins, methods, and headers explicitly.

Because null is not a specific trusted party; it is the serialization of an opaque origin, and an attacker can obtain one trivially by placing their payload inside a sandboxed iframe without allow-same-origin, or by routing through a data URL or certain redirect chains. A policy that allows null therefore grants read access to anyone willing to arrange one of those, which in practice means everyone, while looking in configuration like a narrow exception for an unusual case.

The preflight fails and the real request is never sent. The browser compares the full set of non-safelisted headers the request will carry against the approved list and requires complete coverage, because the alternative, silently dropping unapproved headers, would let a server receive a request that differs from the one the client believed it was making. This is a common regression when a tracing or correlation library starts adding a header automatically.