HTTP OPTIONS Method: CORS, Preflight & API Discovery

CORS Preflight Requests Explained

What is CORS?

CORS (Cross-Origin Resource Sharing) is a browser security mechanism that restricts web pages from making HTTP requests to a different origin (domain, protocol, or port) than the one that served the page. Without CORS, a malicious website could silently make authenticated requests to your API using the user's credentials.

When a web application at https://app.example.com wants to call an API at https://api.example.com, the browser treats this as a cross-origin request and enforces CORS rules.

When Does the Browser Send a Preflight?

Not every cross-origin request triggers a preflight. The browser only sends an OPTIONS preflight for non-simple requests. A request is non-simple if it meets any of these conditions:

• Uses a method other than GET, HEAD, or POST
• Uses POST with a Content-Type other than application/x-www-form-urlencoded, multipart/form-data, or text/plain
• Includes custom request headers (e.g., Authorization, X-Custom-Header)
• Uses credentials (cookies, HTTP authentication)

In practice, virtually every REST API call from a frontend application triggers a preflight, because they use Content-Type: application/json and/or an Authorization header.

Step-by-Step Preflight Flow

STEP 1: Browser wants to make this actual request
  POST https://api.example.com/api/v1/users
  Origin: https://app.example.com
  Content-Type: application/json
  Authorization: Bearer token123

STEP 2: Before sending it, browser sends preflight
  OPTIONS https://api.example.com/api/v1/users
  Origin: https://app.example.com
  Access-Control-Request-Method: POST
  Access-Control-Request-Headers: Content-Type, Authorization

STEP 3: Server responds with CORS permissions
  HTTP/1.1 204 No Content
  Access-Control-Allow-Origin: https://app.example.com
  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
  Access-Control-Allow-Headers: Content-Type, Authorization
  Access-Control-Max-Age: 86400

STEP 4: Browser checks: is POST allowed? Yes.
         Are Content-Type and Authorization allowed? Yes.
         Origin is approved? Yes.

STEP 5: Browser proceeds with the actual POST request.

Full Preflight Request and Response Example

OPTIONS /api/v1/users HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, Authorization
Connection: keep-alive

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400
Vary: Origin
Content-Length: 0

Implementing OPTIONS in Your API

Wildcard Origin vs Specific Origins

The Access-Control-Allow-Origin header has two modes:

• Wildcard (*): Allows any origin. Suitable for truly public APIs with no authentication. Simple to implement but cannot be used with Access-Control-Allow-Credentials: true.
• Specific origin: Echo the exact value of the request's Origin header (after validating it against your allowlist). Required for credentialed requests. Must also include Vary: Origin to prevent cache poisoning.

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 86400

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

Using Access-Control-Max-Age for Performance

Without caching, the browser sends an OPTIONS preflight before every non-simple cross-origin request. On a page that makes 20 API calls, that means 40 HTTP requests instead of 20. The Access-Control-Max-Age header tells the browser to cache the preflight result for a specified number of seconds, eliminating redundant preflight requests.

• Value of 86400 (24 hours) is a good default for stable APIs
• Use lower values (e.g., 300) during development or when CORS config changes frequently
• Browser maximums: Chrome enforces 7200s, Firefox 86400s, Safari varies

Security: Never Use Wildcard with Credentials

The combination of Access-Control-Allow-Origin: * and Access-Control-Allow-Credentials: true is explicitly invalid per the CORS specification. Browsers will reject such responses. This restriction exists by design: if you allow credentials (cookies, auth tokens), you must be specific about which origins you trust. Always validate the request's Origin against an allowlist and echo the approved origin in the response.

Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true    <-- INVALID with wildcard

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Vary: Origin

Common OPTIONS / CORS Mistakes

Mistake 1: Returning 404 or 405 for OPTIONS Requests

If your router does not explicitly handle OPTIONS, it may return a 404 Not Found or 405 Method Not Allowed response. The browser receives this before it can check CORS headers, causing the preflight to fail and the actual request to be blocked. Every route that accepts cross-origin requests must handle OPTIONS — either explicitly or via middleware that intercepts OPTIONS before routing.

Mistake 2: Wildcard Origin with Credentials

As covered above, Access-Control-Allow-Origin: * and Access-Control-Allow-Credentials: true cannot be combined. Browsers reject this combination silently (from the JavaScript perspective) — the fetch or XMLHttpRequest fails with a CORS error, and the network tab shows the response was received but blocked. Always use a specific origin when credentials are involved.

Mistake 3: Missing Vary: Origin Header

When your server returns different values of Access-Control-Allow-Origin depending on the request's Origin, you must also return Vary: Origin. Without it, a CDN or proxy might cache a response with one origin's CORS headers and serve it to a different origin — causing that second origin to see incorrect or absent CORS headers. This produces intermittent CORS failures that are very hard to debug.

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Vary: Origin    <-- Required whenever Access-Control-Allow-Origin varies per request

Mistake 4: Access-Control-Max-Age Too Low or Too High

• Too low (e.g., 0 or 1): The browser preflights every single request, doubling your API call count and adding latency. This is a hidden performance problem that only shows up under realistic traffic.
• Too high: If you change your CORS policy (add a new allowed header, change allowed origins), users' browsers may cache the old preflight response for hours. During incident response, this means users are stuck with the old policy until their cache expires.
• Recommendation: Use 86400 (24 hours) for stable production APIs, 300-3600 for APIs with changing CORS policies.

Mistake 5: Not Including Required Headers in Access-Control-Allow-Headers

If your client sends a custom header — like Authorization, X-Request-ID, or X-API-Version — that header must appear in Access-Control-Allow-Headers. If it is missing, the browser blocks the actual request even after a successful preflight. Check the Access-Control-Request-Headers value in the preflight request to see exactly what the client is asking to send.

Related Topics