Notes

CORS: a practical response-header checklist

Diagnose a blocked browser fetch by checking the origin, preflight response and credential policy. CORS controls what scripts can read; it does not authenticate a request.

A browser reports a CORS error when a cross-origin response does not grant the calling script permission to read it. Start with the request in the Network panel. The console message alone rarely shows enough of the exchange.

An origin is the scheme, hostname and port together. https://app.example and https://api.example are different origins, even though they share a parent domain. A path is not part of an origin.

Check the response

For a public response that any website may read, this is sufficient:

Access-Control-Allow-Origin: *

For a response intended for one browser application, return its exact origin:

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

Use Vary: Origin when the response changes according to the request’s Origin header. It tells HTTP caches that responses for different origins are different variants. Merge it with any existing Vary fields. Do not reflect arbitrary origins for private data; compare against an explicit allowlist.

Request Response requirements
Public fetch without credentials Access-Control-Allow-Origin: * is permitted
Fetch with credentials: "include" Exact allowed origin and Access-Control-Allow-Credentials: true
JSON POST or custom request header Successful preflight allowing the method and headers
Script reads X-Request-Id Access-Control-Expose-Headers: X-Request-Id

These headers belong on the actual response, including application error responses. A successful OPTIONS response does not repair a missing header on a later 401 or 500.

Inspect the preflight separately

A JSON POST typically triggers an OPTIONS request before the POST. Reproduce its shape with curl, replacing the example host with your API:

curl -i -X OPTIONS https://api.example/items \
  -H 'Origin: https://app.example' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type'

A matching response could be:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Vary: Origin

Preflight is normally sent without cookies. Requiring a logged-in session on OPTIONS can therefore block the real request before it starts. Authenticate the real operation separately. Curl displays headers but does not enforce browser CORS rules; a successful curl request does not establish that browser access works.

Credentials need agreement on both sides

The client must request cross-origin credentials, and the server must allow them. An origin wildcard cannot be used for a credentialed response. Cookie SameSite rules and browser third-party-cookie policy still apply independently.

mode: "no-cors" is not a fix for an API fetch. It generally gives the script an opaque response whose body and status it cannot inspect.

CORS also does not stop every unwanted request from reaching your server. Some requests are sent before the browser decides whether the response may be exposed. Keep authentication, authorization and CSRF protection on the server.

For the complete browser decision process, use the CORS dive. The protocol rules are defined in the Fetch Standard; cache variants are explored in HTTP caching.