CORS Explained for REST APIs

"Blocked by CORS policy" is the error every frontend developer meets sooner or later. CORS (Cross-Origin Resource Sharing) isn't a bug or an API security feature – it's the browser relaxing its same-origin policy when your API explicitly says a website may read its responses. Once you know which headers the browser checks, CORS errors take minutes to fix.

Origins

An origin is scheme + host + port: https://app.learnfrenzy.com and https://api.learnfrenzy.com are different origins, and so are http://localhost:5173 and http://localhost:3000. By default, JavaScript on one origin may send requests to another, but the browser won't let it read the response unless the server opts in with CORS headers.

Simple requests and preflight

GET, HEAD and form-style POSTs with simple headers skip the preflight. Anything else – PUT, DELETE, Content-Type: application/json, an Authorization header – triggers one.

CORS in Express

// server.js
import express from 'express';
import cors from 'cors';

const app = express();
app.use(express.json());

const ALLOWED = ['https://app.learnfrenzy.com', 'http://localhost:5173'];

app.use(cors({
  origin: (origin, done) => done(null, !origin || ALLOWED.includes(origin)),   // allow-list, not '*'
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,                                                           // allow cookies / auth
  maxAge: 600,                                                                 // cache preflight for 10 minutes
}));

app.put('/api/profile', (req, res) => res.json({ saved: true, name: req.body.name }));

app.listen(process.env.PORT ?? 3000);

$ curl -X OPTIONS http://localhost:3000/api/profile -H 'Origin: https://app.learnfrenzy.com' -H 'Access-Control-Request-Method: PUT' -H 'Access-Control-Request-Headers: content-type,authorization'
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.learnfrenzy.com
Vary: Origin
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET,POST,PUT,DELETE
Access-Control-Allow-Headers: Content-Type,Authorization
Access-Control-Max-Age: 600

$ curl -X PUT http://localhost:3000/api/profile -H 'Origin: https://app.learnfrenzy.com' -H 'Content-Type: application/json' -d '{"name":"Asha"}'
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.learnfrenzy.com
Vary: Origin
Access-Control-Allow-Credentials: true
Content-Type: application/json; charset=utf-8

{
  "saved": true,
  "name": "Asha"
}

$ curl -X OPTIONS http://localhost:3000/api/profile -H 'Origin: https://evil.example' -H 'Access-Control-Request-Method: PUT'
HTTP/1.1 200 OK
Allow: PUT
Content-Type: text/plain

PUT

• The allowed origin's preflight got 204 with the allowed methods and headers; the real request echoed the exact origin.
• The unknown origin's preflight got Express's default OPTIONS reply but no Access-Control-Allow-Origin header, so the browser refuses to send the real PUT at all.
• Careful: for simple requests (a plain GET or form POST) there is no preflight – the server runs the request and the browser only hides the response from the page. CORS limits what pages can read; it never replaces authentication and CSRF protection.
• Vary: Origin tells caches that the response depends on the origin.

Common mistakes

Practice

Summary