OPTIONS Endpoint Design for CORS Preflights

Without a correctly formed OPTIONS endpoint, every cross-origin non-simple request stalls: the browser issues a preflight and, if it receives a 403, 405, or malformed CORS headers, it blocks the actual request and presents a CORS error in the console. Even a technically correct response carries a latency penalty on every uncached preflight — meaning a slow or bloated OPTIONS handler adds a round-trip cost to every authenticated API call, file upload, or custom-header fetch your application makes.

This page is part of Preflight Request Optimization & Caching Strategies, which covers the full lifecycle from preflight suppression through cache expiry. Here the focus is narrower: how to structure the OPTIONS handler itself so it is fast, correct, and secure.

Spec anchor

The WHATWG Fetch specification (§3.2.2, “CORS-preflight fetch”) defines exactly what the browser sends and what it expects back. The browser constructs an OPTIONS request with three headers: Origin, Access-Control-Request-Method, and optionally Access-Control-Request-Headers. It then reads Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, and Access-Control-Max-Age from the response. Any divergence — missing header, wrong value, body with wrong content-type — does not cause a graceful fallback; it causes an outright block.

Key invariant from the spec: the browser never sends credentials on a preflight. No cookies, no Authorization header. An OPTIONS handler must never require authentication.

Response header reference

Access-Control-Max-Age is the single largest lever for preflight performance. Setting it to 600 reduces Chrome and Safari preflight frequency to at most once every 10 minutes per origin+method+headers combination. Read the full analysis in Cache Duration Tuning & Max-Age.

Preflight request–response flow

The diagram below shows how a browser decides whether to issue a preflight, what the OPTIONS exchange looks like, and what happens to the cached result.

Step-by-step implementation

1. Intercept at the reverse proxy (Nginx)

For high-traffic services, intercepting OPTIONS before the request reaches the application server eliminates framework initialization overhead entirely. This is the proxy bypass approach applied at the OPTIONS layer.

map $http_origin $cors_origin {
  default                        "";
  "https://app.example.com"      $http_origin;
  "https://admin.example.com"    $http_origin;
}

server {
  location /api/ {
    if ($request_method = OPTIONS) {
      add_header Access-Control-Allow-Origin  $cors_origin always;
      add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
      add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-Request-ID" always;
      add_header Access-Control-Max-Age       600 always;
      add_header Vary                         Origin always;
      return 204;
    }

    proxy_pass http://backend;
    add_header Access-Control-Allow-Origin $cors_origin always;
    add_header Vary                        Origin always;
  }
}

The map block performs origin validation once per connection in Nginx’s rewrite phase — faster and more predictable than if blocks inside location. The always flag ensures CORS headers are present even on error responses, which prevents double-failure scenarios where a 502 from the backend also strips the CORS headers and forces an opaque error in the browser.

2. Application-level handler (Express / Node.js)

When proxy-level handling is not available or you need per-route logic, handle OPTIONS in the application before authentication or business logic middleware:

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

const ALLOWED_HEADERS = new Set([
  'content-type',
  'authorization',
  'x-request-id',
]);

const ALLOWED_METHODS = 'GET, POST, PUT, DELETE, OPTIONS';

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

  // OPTIONS must never require auth — short-circuit before any auth middleware
  if (req.method !== 'OPTIONS') {
    return next();
  }

  if (origin && ALLOWED_ORIGINS.has(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Vary', 'Origin');
  } else {
    // Unknown origin: return 204 with no CORS headers — browser will block the real request
    return res.status(204).end();
  }

  // Validate requested headers against allowlist before reflecting
  const requested = (req.headers['access-control-request-headers'] || '')
    .split(',')
    .map(h => h.trim().toLowerCase())
    .filter(h => ALLOWED_HEADERS.has(h));

  res.setHeader('Access-Control-Allow-Methods', ALLOWED_METHODS);
  res.setHeader('Access-Control-Allow-Headers', requested.join(', '));
  res.setHeader('Access-Control-Max-Age', '600');

  return res.status(204).end();
}

// Mount before all other middleware, including auth
app.use(corsPreflightHandler);

The critical ordering constraint: corsPreflightHandler must be mounted before any authentication or session middleware. Auth middleware that returns 401 on an OPTIONS request breaks all preflights — the browser sees the 401 as a CORS failure and never retries.

3. FastAPI / Python (ASGI middleware)

from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
from starlette.responses import Response

ALLOWED_ORIGINS = {"https://app.example.com", "https://admin.example.com"}
ALLOWED_HEADERS = {"content-type", "authorization", "x-request-id"}
ALLOWED_METHODS = "GET, POST, PUT, DELETE, OPTIONS"

class CORSPreflightMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        origin = request.headers.get("origin", "")

        if request.method != "OPTIONS":
            response = await call_next(request)
            if origin in ALLOWED_ORIGINS:
                response.headers["Access-Control-Allow-Origin"] = origin
                response.headers["Vary"] = "Origin"
            return response

        # Preflight path — never reaches application routes
        if origin not in ALLOWED_ORIGINS:
            return Response(status_code=204)

        requested_raw = request.headers.get("access-control-request-headers", "")
        requested = [
            h.strip().lower()
            for h in requested_raw.split(",")
            if h.strip().lower() in ALLOWED_HEADERS
        ]

        return Response(
            status_code=204,
            headers={
                "Access-Control-Allow-Origin": origin,
                "Access-Control-Allow-Methods": ALLOWED_METHODS,
                "Access-Control-Allow-Headers": ", ".join(requested),
                "Access-Control-Max-Age": "600",
                "Vary": "Origin",
            },
        )

Add this middleware before AuthenticationMiddleware in your ASGI stack.

Edge cases and security boundaries

Subdomain isolation

Origin comparison is exact: https://api.example.com and https://app.example.com are distinct origins. Never use substring matching or suffix matching (endsWith('.example.com')) as an allowlist check — a domain like evil.notexample.com would pass a naive suffix test. Use a Set or array of complete origin strings.

The null origin

Requests from sandboxed iframes, data: URIs, or file:// documents send Origin: null. Never include null in your origin allowlist — doing so would allow any sandboxed page anywhere on the web to pass your preflight. If you need to support sandboxed iframes you control, use allow-same-origin on the sandbox attribute instead.

Opaque responses and no-cors mode

When the browser uses no-cors mode, it does not send a preflight and does not expose the response to JavaScript. Your OPTIONS handler will not be called in this scenario. The security boundary here is that the response is opaque — the page cannot read it, only trigger side effects.

Credentials and Access-Control-Allow-Origin: *

If your actual (non-OPTIONS) responses need to support credentialed requests, you must reflect the exact origin (not *) in Access-Control-Allow-Origin and include Access-Control-Allow-Credentials: true. The wildcard risks and mitigation page covers why * and credentials are mutually exclusive per the Fetch spec. This same constraint applies to the preflight response — setting * on OPTIONS while requiring credentials on the real request will cause the actual fetch to fail.

Auth middleware returning 401 on OPTIONS

The WHATWG Fetch spec (§3.2.2 step 7) requires the preflight response status to be in the range 200–299 for the preflight to succeed. A 401 from JWT or session middleware terminates the preflight. The fix is middleware ordering: the OPTIONS short-circuit must precede the auth stack entirely.

Proxy and CDN interaction

CDNs and shared reverse proxies will cache preflight responses if you include Cache-Control headers alongside Access-Control-Max-Age. However, the browser’s preflight cache is separate from the HTTP cache — Access-Control-Max-Age controls the browser-side preflight cache specifically. To avoid serving stale or cross-origin-polluted preflight responses from edge caches, always include Vary: Origin in OPTIONS responses.

Without Vary: Origin, a CDN may cache a preflight response for https://app.example.com and serve it in response to a preflight from https://admin.example.com. That response will contain the wrong Access-Control-Allow-Origin value, causing the second origin’s requests to fail. The header deduplication techniques page explains how to consolidate response headers to minimize Vary key explosion.

For CDNs that cache responses aggressively (Cloudflare, CloudFront, Fastly), explicitly configure your preflight routes to either bypass the cache (Cache-Control: no-store on OPTIONS) or ensure Vary: Origin is respected in your CDN’s cache settings — some CDN configurations strip Vary headers by default.

DevTools and curl verification checklist

Use this checklist after deploying changes to an OPTIONS handler:

• Run curl -sI -X OPTIONS https://api.example.com/v1/resource -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: Content-Type, Authorization" and confirm response status is 204
• Verify Access-Control-Allow-Origin in the response matches the exact origin sent — not * if credentials are in use
• Verify Access-Control-Allow-Methods includes the method being requested
• Verify Access-Control-Allow-Headers reflects only headers from your allowlist
• Verify Access-Control-Max-Age is present and set to an integer (e.g. 600)
• Verify Vary: Origin is present
• In browser DevTools → Network tab, filter by “Other” or “Preflight” and confirm the OPTIONS request shows status 204
• After the first successful preflight, reload and confirm no second OPTIONS request fires within the max-age window (Chrome caps at 600 s)
• Send an OPTIONS with an unlisted origin and confirm the response omits Access-Control-Allow-Origin entirely
• Confirm the response body is empty (Content-Length: 0 or no body)
• Confirm your auth middleware does not intercept OPTIONS: send OPTIONS without any Authorization header and confirm 204, not 401

Common mistakes

FAQ