CORS Header Explainer

The CORS Header Explainer provides an interactive reference and configuration validator for Cross-Origin Resource Sharing headers, helping you understand, debug, and fix CORS errors without trial-and-error deployment cycles. Enter your request origin, method, and custom headers alongside the server's CORS response headers, and see instantly whether the browser would allow or block the request -- with a clear explanation of why.

Understanding CORS

If you have ever seen the message "Access to XMLHttpRequest has been blocked by CORS policy" in your browser console, you have encountered one of the web's most common and most confusing security mechanisms. CORS stands for Cross-Origin Resource Sharing, and it exists to protect users from malicious websites that try to make requests to other sites on the user's behalf. Without CORS, any webpage you visit could silently send requests to your bank's API using your logged-in session -- CORS prevents this by requiring the bank's server to explicitly opt in to receiving requests from other origins.

An origin is defined by the combination of scheme, host, and port: https://app.example.com and https://api.example.com are different origins even though they share the same root domain. When your frontend JavaScript at https://app.example.com makes a fetch request to https://api.example.com/data, the browser checks whether the API server has sent the right CORS headers saying it permits requests from https://app.example.com. If the headers are missing or incorrect, the browser blocks the response from reaching your JavaScript, even though the server actually processed the request and sent back data.

The confusion around CORS comes from its layered design. Simple requests -- basic GET or POST with standard headers -- go through directly, and the browser checks the CORS headers on the response. But any request that uses custom headers, non-standard content types, or methods like PUT or DELETE triggers a preflight check: the browser sends an OPTIONS request first to ask the server whether it will accept the real request. The server must respond to this preflight with the correct Access-Control-Allow-* headers before the browser will send the actual request. This tool simulates both scenarios so you can validate your configuration before deploying.

How to Check a CORS Configuration

1. Enter the request origin (e.g., https://app.example.com), HTTP method, and any custom headers your frontend sends.
2. Enter the server's CORS response headers (Access-Control-Allow-Origin, Access-Control-Allow-Methods, etc.).
3. Click Check to simulate browser CORS validation.
4. Review the result: the tool explains whether the request would be allowed or blocked and identifies the exact reason for any failure.

CORS Header Examples

Simple Request (Allowed)

Result: Allowed. The origin matches exactly.

Preflight Request with Custom Headers (Allowed)

Result: Allowed. The origin, method, and headers all match. Preflight is cached for 24 hours.

Credentials Request (Blocked)

Result: Blocked. When Access-Control-Allow-Credentials is true, the Access-Control-Allow-Origin header cannot be the wildcard * -- it must specify the exact origin.

When to Use the CORS Header Explainer

• Debugging "CORS error" in browser consoles -- Paste your request details and server headers to find out exactly why the browser is blocking the request.
• Setting up API CORS configuration -- Validate your Access-Control-* headers before deploying to production.
• Configuring CDN or reverse proxy headers -- Test CORS header passthrough when using CloudFront, Cloudflare, or nginx as a proxy.
• Understanding preflight vs. simple requests -- Learn which request characteristics trigger a preflight OPTIONS request.
• Fixing credentials and cookie issues -- Diagnose why cookies or Authorization headers are not being sent in cross-origin requests.
• Training and documentation -- Use the interactive checker as a teaching tool for developers learning CORS for the first time.

How CORS Works

Simple Requests vs. Preflight Requests

Browsers classify cross-origin requests into two categories:

Simple requests are sent directly without a preflight check. A request is "simple" when it uses GET, HEAD, or POST with only standard headers (Accept, Accept-Language, Content-Language, Content-Type limited to application/x-www-form-urlencoded, multipart/form-data, or text/plain).

Preflight requests are triggered for anything outside the simple request criteria. The browser sends an OPTIONS request first, and the server must respond with appropriate Access-Control-Allow-* headers before the actual request is sent.

CORS Header Reference

Common CORS Mistakes

• Setting Access-Control-Allow-Origin: * with Access-Control-Allow-Credentials: true -- this combination is explicitly forbidden by the spec.
• Forgetting to include Content-Type in Access-Control-Allow-Headers when sending JSON -- application/json is not a "simple" content type.
• Not handling the OPTIONS preflight method on the server, resulting in a 405 Method Not Allowed response.
• Omitting Access-Control-Expose-Headers and wondering why JavaScript cannot read custom response headers.

CORS Validation Flow

Browser                                    Server
  |                                          |
  |-- Is this a simple request? ------------>|
  |   (GET/HEAD/POST, standard headers)      |
  |                                          |
  |   YES: Send request directly             |
  |   NO: Send OPTIONS preflight first       |
  |                                          |
  |<--- Preflight response ------------------|
  |   Access-Control-Allow-Origin: ...       |
  |   Access-Control-Allow-Methods: ...      |
  |   Access-Control-Allow-Headers: ...      |
  |                                          |
  |-- Check: Does origin match? ------------>|
  |-- Check: Is method allowed? ------------>|
  |-- Check: Are headers allowed? ---------->|
  |                                          |
  |   ALL PASS: Send actual request          |
  |   ANY FAIL: Block and log CORS error     |

Practical Tips for CORS Configuration

The safest approach to CORS configuration is to start with the most restrictive settings and open up only what your application needs. Begin by specifying the exact origins that should have access rather than using *. If your frontend is at https://app.example.com, set Access-Control-Allow-Origin: https://app.example.com explicitly. This prevents any other site from making cross-origin requests to your API. If you need to support multiple origins, implement dynamic origin checking on the server -- read the Origin request header, check it against your allowlist, and echo it back in the response.

Preflight caching is an often-overlooked optimization. Without Access-Control-Max-Age, the browser sends an OPTIONS preflight request before every single cross-origin request. On an application that makes frequent API calls, this doubles the number of requests. Setting Access-Control-Max-Age: 3600 (1 hour) tells the browser to cache the preflight result, eliminating redundant OPTIONS requests. Note that most browsers cap this at around 7,200 seconds (2 hours), and Chrome caps it at 2 hours even if you set a higher value.

When your API needs to return custom response headers that JavaScript should read (like pagination info in X-Total-Count or request IDs in X-Request-ID), you must list them in Access-Control-Expose-Headers. By default, JavaScript can only read a small set of "CORS-safelisted" response headers: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, and Pragma. Any custom header is invisible to your frontend code unless you expose it explicitly. This is a common source of confusion when debugging pagination or rate-limit display issues.

Frequently Asked Questions

Why does my request work in Postman but fail in the browser?

Postman and other API clients do not enforce CORS because CORS is a browser-only security mechanism. The same-origin policy is enforced by the browser to protect users from malicious scripts. Server-to-server requests are unaffected by CORS.

Can I use Access-Control-Allow-Origin: * with cookies?

No. When the request includes credentials (cookies, HTTP authentication), the server must respond with the exact requesting origin, not *. Set Access-Control-Allow-Origin: https://app.example.com and Access-Control-Allow-Credentials: true together.

What is Access-Control-Max-Age and should I set it?

It tells the browser how long to cache the preflight response. Without it, the browser sends an OPTIONS request before every cross-origin request. Setting it to 86400 (24 hours) reduces preflight overhead significantly. Most browsers cap it at 7200 seconds (2 hours) regardless of the value you set.

Why do I get a CORS error even though the server returns 200?

CORS is enforced by the browser, not the server. The server processes the request and sends a 200 response, but if the response lacks the correct Access-Control-Allow-Origin header, the browser blocks JavaScript from accessing the response data. The request succeeds on the server side -- you just cannot read the result from your frontend.

How do I handle CORS for WebSocket connections?

WebSocket connections do not use CORS. The initial HTTP handshake that upgrades to WebSocket is not subject to CORS preflight. However, you should still validate the Origin header on the server side during the WebSocket handshake to prevent cross-origin WebSocket hijacking.

Can I use CORS to restrict which servers can call my API?

No. CORS only restricts browser-based requests. Any server, script, or command-line tool can call your API directly without CORS restrictions. For server-to-server authentication, use API keys, OAuth tokens, or mutual TLS. CORS is specifically a browser security feature, not a general access control mechanism.

Related Tools

• HTTP Header Formatter - Parse and format HTTP headers including CORS headers
• HTTP Status Code Lookup - Look up status codes returned during preflight failures
• Cookie Header Parser - Parse cookies that interact with CORS credential settings
• curl Command Builder - Build curl commands to test CORS-enabled endpoints
• MIME Type Lookup - Look up Content-Type values that affect simple vs. preflight CORS decisions