CORS and browser-facing APIs

Maya's app runs at app.example.com and calls the API at api.example.com. The browser console says: "blocked by CORS policy." A teammate wants to "just allow everything". That would hand every website the keys to your users' accounts. Your goal: set up CORS safely.

The wall that CORS opens a door in

Browsers enforce the same-origin policy. A script on one origin may send requests to another origin. But by default it cannot read the reply. An origin is the scheme, host and port together. So https://app.example.com and https://api.example.com are different origins, and so are http and https.

CORS (cross-origin resource sharing) lets the server opt in. It allows chosen other origins to read its replies. CORS does not add a restriction. It relaxes one.

Simple requests and preflight

A simple request is sent straight to the server. Only reading the reply is gated. A request is simple only when all three are true. It uses GET, HEAD or POST. It sets only a short list of safe headers. If it has a body, the type is application/x-www-form-urlencoded, multipart/form-data or text/plain.

Anything else is preflighted. Examples: a PUT or DELETE; an Authorization header or a custom X- header; a JSON body with Content-Type: application/json.

A preflight is a separate OPTIONS request the browser sends first. It asks: "may I send this?" Only if the server's answer allows it does the browser send the real request.

CSRF: the other half

CSRF (cross-site request forgery) is when a bad page makes the victim's browser fire a request at your API. The browser adds the victim's cookies by itself. A form-encoded POST is a simple request, so it goes through at once. The main brake is the SameSite cookie setting. It tells the browser not to attach the cookie to requests that another site started. Add checks on requests that change things. CORS decides who can read; SameSite and CSRF checks decide what can change.

The mistake that undoes it all

To use cookies across origins, the browser needs Access-Control-Allow-Credentials: true and an exact origin. The wildcard * is forbidden with credentials. So a team often writes code that repeats back whatever origin asked. Then any website a user visits can make the browser call your API with that user's cookies, and read the reply. Repeating back the origin with credentials is the same as allowing every origin.

The safe pattern is a short, exact allowlist. Compare the incoming Origin with known-good origins. If it matches, send back that one origin, and add Vary: Origin. If not, send no CORS headers. Match exactly. A "contains" check is a trap. example.com.evil.com and notexample.com both contain "example.com".

What CORS is not

• CORS is not sign-in. You still need tokens or sessions, and permission checks on every request.
• CORS does nothing outside browsers. A script, bot or server ignores the headers. So a strict CORS policy does not stop scraping. Sign-in and rate limits do.