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

CORS Preflight Request Explained (OPTIONS)

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: A Complete Preflight Exchange
  4. Real-World Examples
  5. Review Questions & Answers

Learning Objective

Trace a complete preflight exchange header by header, explain what the browser asks and what the server must answer for the real request to proceed, and reason about the caching behavior controlled by Access-Control-Max-Age.

Concept Explanation

A preflight is a separate HTTP OPTIONS request the browser sends on its own initiative, before the real request, to ask the target server whether the real request is permitted. It is not visible to the page's JavaScript, it carries no request body, and critically it carries no credentials: no cookies, no client certificate, no HTTP authentication, regardless of what the actual request will use. That last point trips people up regularly, because it means a server cannot authenticate the preflight and must be able to answer it for anonymous callers.

The browser puts three headers on the preflight. Origin carries the requesting origin, exactly as computed in this course's first lesson. Access-Control-Request-Method names the method the real request will use. Access-Control-Request-Headers lists, comma-separated and lowercased, every non-safelisted header the real request will set. The server's job is to answer with a 2xx status and a set of Access-Control-Allow-* headers that cover everything the browser asked about. If any requested method or header is missing from the answer, or the status is an error, or the Origin is not approved, the browser aborts and never sends the real request at all.

This is the one place in CORS where the mechanism genuinely prevents a request rather than merely withholding a response, and it is why forcing a preflight is a meaningful hardening technique. For a preflighted request, an attacker's page cannot cause any side effect on the server, because the browser refuses to dispatch the real request when the preflight is not approved. For a simple request, the side effect happens first and the CORS check applies only to the reply.

Access-Control-Max-Age controls how long the browser may cache the preflight result for this origin, method, and header combination, in seconds. Without it, every single cross-origin call pays an extra round trip, which on a chatty API is a serious performance problem. With it, one preflight covers many subsequent requests. Browsers cap the value: Chromium enforces a maximum of 7200 seconds, two hours, and Firefox 86400 seconds, so a server sending 31536000 is silently clamped, not honored. The cache is also keyed per request configuration, so a client that varies its headers across calls will preflight each distinct combination separately.

Two operational details matter when debugging. First, a preflight that returns 401 or 403 because an authentication middleware ran before the CORS middleware is one of the most common causes of "CORS errors" that are not really CORS problems at all; the OPTIONS request must be answered before authentication, precisely because it carries no credentials. Second, if the server varies its Access-Control-Allow-Origin per requesting origin, it must send Vary: Origin, otherwise a shared cache or CDN can store the response computed for one origin and serve it to another, which both breaks the site and can leak an approval to an origin that was never granted one.

Preflight request headerSet byServer must answer with
OriginThe browser, from the requesting documentAccess-Control-Allow-Origin echoing that origin, or a wildcard
Access-Control-Request-MethodThe browser, naming the real methodAccess-Control-Allow-Methods including that method
Access-Control-Request-HeadersThe browser, listing non-safelisted headersAccess-Control-Allow-Headers covering every listed header
(none: no cookies are sent)Deliberately omitted by the browserA 2xx response reachable without authentication

Worked Example: A Complete Preflight Exchange

Below is the full two-round-trip sequence for a cross-origin PUT carrying JSON and an Authorization header. Note that the OPTIONS request has no Cookie header even though the real request does, and that the server answers every question the browser asked.

HTTP
# ---- ROUND 1: the browser asks permission (no credentials, no body) ----
OPTIONS /v1/documents/42 HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: authorization,content-type

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 7200
Vary: Origin

# ---- ROUND 2: only now is the real request sent ----
PUT /v1/documents/42 HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Cookie: session=...

{"title":"Q4 plan"}

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Vary: Origin
Content-Type: application/json

{"ok":true}

# If ROUND 1 had omitted Access-Control-Allow-Headers: Authorization,
# the browser would abort and ROUND 2 would never be sent at all.
The two-round-trip preflight sequence as a timeline, with the OPTIONS question and its three request headers on the left, the server answer in the middle, and the gate where the browser either dispatches or aborts the real request.
The two-round-trip preflight sequence as a timeline, with the OPTIONS question and its three request headers on the left, the server answer in the middle, and the gate where the browser either dispatches or aborts the real request.

Real-World Examples

  • Chrome shipped Private Network Access preflights, originally proposed as CORS-RFC1918, which require a public web page to obtain an explicit preflight approval carrying Access-Control-Allow-Private-Network before it may issue requests to private IP ranges or localhost; the feature exists because of documented attacks in which malicious public pages reconfigured home routers and reached internal services through the victim's browser, and it extends the preflight gate to a threat the original CORS design did not anticipate.
  • Browsers cap Access-Control-Max-Age rather than honoring arbitrary values, with Chromium enforcing a two-hour ceiling and Firefox a twenty-four-hour one, which is a frequent source of confusion for teams that set a year-long max age and still observe a preflight on most requests; the cap exists so that a policy change made by a server takes effect within a bounded window rather than remaining cached in clients indefinitely.
Common PitfallAnswer OPTIONS requests before your authentication middleware runs. A preflight carries no cookies and no Authorization header by design, so an auth layer that rejects it with 401 turns every cross-origin call into a browser-reported CORS failure that no amount of adjusting your Allow headers will fix.

Review Questions & Answers

The preflight is a question about policy, not a request for a resource, and sending credentials on it would mean an unapproved cross-origin interaction had already occurred with the user's identity attached. Because it is anonymous, the server must be able to answer it without authentication, which means the CORS handling for OPTIONS has to sit ahead of any authentication middleware in the request pipeline.

The preflight is the one point where the browser withholds the request itself rather than the response. If the server does not approve the preflight, the real request is never dispatched, so no side effect occurs. A simple request has no such gate: it is sent, the server acts on it, and only the reply is withheld. That is why forcing a preflight, through a custom header or a strictly enforced JSON content type, converts a CORS mechanism into a genuine request-blocking one.

Browsers clamp the value to their own maximum, two hours in Chromium and twenty-four hours in Firefox, so the year-long value is silently reduced. Additionally, the preflight cache is keyed by the exact combination of origin, method, and requested headers, so a client that varies its headers between calls will trigger a separate preflight for each distinct combination regardless of the max age in force.

Because the response now depends on a request header, and any intermediary cache that does not know that will store the response generated for one origin and replay it to requests from another. In the benign case the site breaks for the second origin; in the worse case an approval computed for a trusted origin is served to an untrusted one, handing it read access it was never granted. Vary: Origin tells every cache to key on the requesting origin.