Cross-Origin Resource Sharing (CORS) is a browser security mechanism that controls whether JavaScript running on one website can access resources from another. It extends the Same-Origin Policy (SOP) — the browser’s fundamental security boundary that prevents one site from reading data belonging to another.
\nAn origin is defined by three components:
\nhttp:// vs. https://example.com vs. api.example.com:3000 vs. :8080Any difference in these components makes a request cross-origin, which requires explicit permission from the target server.
\n// Same-origin requests (no CORS needed)\nfetch('/api/users') // Relative URL\nfetch('https://myapp.com/api/data') // Matches protocol, domain, and port\n\n// Cross-origin requests (CORS required)\nfetch('https://api.myapp.com/users') // Different subdomain\nfetch('http://myapp.com/api/users') // Different protocol\nfetch('https://myapp.com:8080/api/users') // Different portThe Same-Origin Policy exists to prevent malicious websites from silently reading your data from other sites — like your email, banking details, or session tokens.
\nA CORS error occurs when your browser blocks a response because the server didn’t include the required permission headers. Here’s what typically happens:
\nhttp://localhost:3000 makes a request to https://api.yourservice.com\n\nCritical insight: The request often completes successfully on the server. CORS doesn’t prevent requests — it prevents your JavaScript from reading the response. This distinction matters when debugging issues like duplicate database records despite seeing a console error.
\n
The browser categorizes HTTP requests into two types for CORS purposes.
\nSimple requests proceed without a preflight check:
\nGET, HEAD, or POSTContent-Type limited to application/x-www-form-urlencoded, multipart/form-data, or text/plain\n\nTerminology note: The term “simple requests” comes from the older CORS spec. The current Fetch Standard doesn’t use this term, but browser behavior remains the same: these requests are sent directly, and the browser checks the
\nAccess-Control-Allow-Originresponse header afterward.
Preflighted requests require an OPTIONS check first:
GET, HEAD, or POSTAuthorization or X-API-KeyPOST with Content-Type: application/jsonHere’s the full preflight flow:
\n# 1. Browser sends preflight (OPTIONS)\nOPTIONS /api/users HTTP/1.1\nOrigin: http://localhost:3000\nAccess-Control-Request-Method: POST\nAccess-Control-Request-Headers: Content-Type, Authorization\n\n# 2. Server grants permission\nHTTP/1.1 204 No Content\nAccess-Control-Allow-Origin: http://localhost:3000\nAccess-Control-Allow-Methods: POST, GET, OPTIONS\nAccess-Control-Allow-Headers: Content-Type, Authorization\nVary: Origin\n\n# 3. Browser sends actual request\nPOST /api/users HTTP/1.1\nOrigin: http://localhost:3000\nContent-Type: application/json\n\n{\"name\": \"New User\"}\n\n# 4. Server responds (must include CORS headers again)\nHTTP/1.1 201 Created\nAccess-Control-Allow-Origin: http://localhost:3000\n\n{\"id\": 123, \"name\": \"New User\"}This two-step process explains why JSON API calls appear slower in browsers than in Postman — browsers complete the preflight first, while tools like Postman bypass CORS entirely.
\nThe most common CORS error. The server processed the request but didn’t include the header that authorizes your origin to read the response.
\nfetch('https://api.coolservice.com/data')\n .then(res => res.json())\n .then(data => console.log(data))\n\n// Error:\n// Access to fetch at 'https://api.coolservice.com/data' from origin\n// 'http://localhost:3000' has been blocked by CORS policy:\n// No 'Access-Control-Allow-Origin' header is present on the requested resource.For servers you control:
\napp.use((req, res, next) => {\n res.header('Access-Control-Allow-Origin', 'http://localhost:3000');\n next();\n});For third-party APIs, you’ll need a proxy server or the API must natively support CORS.
\nThe server accepts cross-origin requests, but not the HTTP method you’re using.
\nfetch('https://api.example.com/users/123', {\n method: 'DELETE',\n headers: { 'Authorization': 'Bearer token' }\n})\n\n// Error:\n// Method DELETE is not allowed by Access-Control-Allow-Methods in preflight response.Common causes: missing OPTIONS endpoint handler, or incomplete method list in the CORS configuration.
This error appears when you send cookies or auth headers cross-origin but the server uses a wildcard origin.
\nfetch('https://api.example.com/profile', {\n credentials: 'include'\n})\n\n// Error:\n// The value of the 'Access-Control-Allow-Origin' header must not be the wildcard '*'\n// when the request's credentials mode is 'include'.When credentials are involved, the server must:
\n*)Access-Control-Allow-Credentials: trueres.header('Access-Control-Allow-Origin', 'http://localhost:3000');\nres.header('Access-Control-Allow-Credentials', 'true');This is a hard browser rule: Access-Control-Allow-Origin: * combined with Access-Control-Allow-Credentials: true will always be rejected. Any server misconfigured this way exposes sensitive user data.
Fetch and Axios handle CORS failures differently:
\n// Fetch — generic, unhelpful error message\nfetch('https://api.example.com/data')\n .catch(error => {\n console.log(error.message); // \"Failed to fetch\" (no detail)\n });\n\n// Axios — structured error information\naxios.get('https://api.example.com/data')\n .catch(error => {\n if (error.response) {\n console.log('Server error:', error.response.status);\n } else if (error.request) {\n console.log('No response received:', error.message);\n }\n });Also note: Axios automatically sets Content-Type: application/json on requests with a body, which triggers a preflight. Any interceptors that add custom headers will also trigger preflight. Check your Axios configuration if requests fail even on seemingly “simple” endpoints.
CORS is fundamentally a server-side configuration problem. Frontend workarounds can help during development, but production requires proper backend setup.
\n// Exact origin (required for credentialed requests)\nres.header('Access-Control-Allow-Origin', 'https://app.example.com');\n\n// Allowed methods\nres.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');\n\n// Allowed request headers\nres.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-API-Key');\n\n// Allow cookies and auth headers\nres.header('Access-Control-Allow-Credentials', 'true');\n\n// Cache preflight for 24 hours (reduces OPTIONS round-trips)\nres.header('Access-Control-Max-Age', '86400');\n\n// IMPORTANT: Tell caches that responses vary by origin\nres.header('Vary', 'Origin');\n\nWhy
\nVary: Originmatters: When your server dynamically reflects the requesting origin (rather than using*), you must includeVary: Originin your responses. Without it, CDNs and shared caches may serve a response with one origin’sAccess-Control-Allow-Originto a different origin — which either breaks CORS or creates a security hole.
cors Packageconst cors = require('cors');\n\nconst corsOptions = {\n origin: function (origin, callback) {\n const allowedOrigins = [\n 'https://app.example.com',\n 'https://admin.example.com',\n 'http://localhost:3000'\n ];\n\n // Allow server-to-server requests (no origin header)\n if (!origin) return callback(null, true);\n\n if (allowedOrigins.includes(origin)) {\n callback(null, true);\n } else {\n callback(new Error('Not allowed by CORS'));\n }\n },\n credentials: true,\n methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],\n allowedHeaders: ['Content-Type', 'Authorization'],\n maxAge: 86400\n};\n\napp.use(cors(corsOptions));\n\n// Explicitly handle preflight for all routes\napp.options('*', cors(corsOptions));from flask import Flask, jsonify, request\nfrom flask_cors import CORS\n\napp = Flask(__name__)\nCORS(app, origins=[\"https://app.example.com\"], supports_credentials=True)\n\n@app.after_request\ndef after_request(response):\n origin = request.headers.get('Origin')\n if origin in ['https://app.example.com', 'http://localhost:3000']:\n response.headers['Access-Control-Allow-Origin'] = origin\n response.headers['Access-Control-Allow-Credentials'] = 'true'\n response.headers['Access-Control-Allow-Methods'] = 'GET, POST, PUT, DELETE, OPTIONS'\n response.headers['Access-Control-Allow-Headers'] = 'Content-Type, Authorization'\n response.headers['Vary'] = 'Origin'\n return response# settings.py\nINSTALLED_APPS = [\n 'corsheaders',\n # ...\n]\n\nMIDDLEWARE = [\n 'corsheaders.middleware.CorsMiddleware', # Must be before CommonMiddleware\n 'django.middleware.common.CommonMiddleware',\n # ...\n]\n\nCORS_ALLOWED_ORIGINS = [\n \"http://localhost:3000\",\n \"https://app.example.com\",\n]\n\nCORS_ALLOW_CREDENTIALS = True\n\nCORS_ALLOW_HEADERS = [\n 'accept',\n 'authorization',\n 'content-type',\n 'x-csrftoken',\n]@Configuration\n@EnableWebMvc\npublic class WebConfig implements WebMvcConfigurer {\n\n @Override\n public void addCorsMappings(CorsRegistry registry) {\n registry.addMapping(\"/api/**\")\n .allowedOrigins(\"https://app.example.com\", \"http://localhost:3000\")\n .allowedMethods(\"GET\", \"POST\", \"PUT\", \"DELETE\", \"OPTIONS\")\n .allowedHeaders(\"Content-Type\", \"Authorization\")\n .allowCredentials(true)\n .maxAge(3600);\n }\n}Adding CORS headers on the frontend has no effect. CORS headers are server responses — the browser ignores them if you try to set them in a fetch() call:
// This does nothing — CORS headers belong on the server\nfetch('https://api.example.com/data', {\n headers: {\n 'Access-Control-Allow-Origin': '*',\n }\n})no-cors mode makes responses unreadable. You can send the request, but JavaScript cannot access the response body:
fetch('https://api.example.com/data', { mode: 'no-cors' })\n .then(response => response.json()) // Throws — response is \"opaque\"Route your frontend through a local proxy during development so requests appear same-origin:
\n// vite.config.js\nexport default {\n server: {\n proxy: {\n '/api': {\n target: 'https://api.example.com',\n changeOrigin: true,\n rewrite: (path) => path.replace(/^\\/api/, '')\n }\n }\n }\n}// next.config.js\nmodule.exports = {\n async rewrites() {\n return [\n {\n source: '/api/:path*',\n destination: 'https://api.example.com/:path*'\n }\n ];\n }\n};Authentication adds extra complexity to CORS because credentials require stricter rules.
\nWhen you send cookies or HTTP auth headers cross-origin (using credentials: 'include'), the browser enforces two additional rules:
Access-Control-Allow-Origin must be an exact origin, never *Access-Control-Allow-Credentials: true// Frontend\nfetch('https://api.example.com/profile', {\n credentials: 'include',\n headers: { 'Content-Type': 'application/json' }\n});// Backend\nres.header('Access-Control-Allow-Origin', 'https://app.example.com'); // Exact origin\nres.header('Access-Control-Allow-Credentials', 'true');For cross-origin cookies to work at all, they must be set with SameSite=None and Secure:
res.cookie('session', token, {\n httpOnly: true,\n secure: true, // HTTPS required\n sameSite: 'none' // Required for cross-origin\n});\n\nBrowser note: Safari is notably stricter about cross-origin cookies than Chrome or Firefox. If your auth flows work in Chrome but fail in Safari, this is usually the cause. Third-party cookie restrictions in Safari’s ITP (Intelligent Tracking Prevention) can block credentialed CORS requests even with correct headers.
\n
Getting this cookie configuration right by hand is error-prone, which is one reason many teams reach for a dedicated session-management layer. SuperTokens sets these SameSite=None; Secure; HttpOnly cookie flags and the matching CORS headers for you, so cross-origin authenticated requests work consistently across browsers. If you’re weighing cookies against other storage options, see Cookies vs. localStorage for sessions and how session-based authentication works.
Access-Control-Allow-Origin: * disables all the security benefits of CORS for that endpoint. Any website can read responses from your API.
// Environment-aware origin whitelist\nconst allowedOrigins = {\n production: ['https://app.yourcompany.com', 'https://www.yourcompany.com'],\n staging: ['https://staging.yourcompany.com'],\n development: ['http://localhost:3000', 'http://localhost:3001']\n};\n\napp.use(cors({\n origin: (origin, callback) => {\n const env = process.env.NODE_ENV || 'development';\n const allowed = allowedOrigins[env];\n\n if (!origin || allowed.includes(origin)) {\n callback(null, true);\n } else {\n console.error(`CORS rejected: ${origin}`);\n callback(new Error('CORS policy violation'));\n }\n }\n}));Exception: Public, read-only APIs with no user data or authentication can safely use *.
Only allow the HTTP methods and headers your application actually uses. Every additional method or header is additional attack surface.
\n// Too permissive — avoid in production\nres.header('Access-Control-Allow-Methods', '*');\n\n// Better — list only what's needed\nres.header('Access-Control-Allow-Methods', 'GET, POST');\nres.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');If DELETE is allowed but not needed, an attacker could potentially trigger deletion via a CSRF attack.
Vary: OriginWhen dynamically reflecting the requesting origin (the most common production pattern), include Vary: Origin to prevent cache poisoning:
// When reflecting origin dynamically, always add Vary\nif (allowedOrigins.includes(req.headers.origin)) {\n res.header('Access-Control-Allow-Origin', req.headers.origin);\n res.header('Vary', 'Origin');\n}Without this, a CDN may cache a response with Access-Control-Allow-Origin: https://app.example.com and serve it to a request from a different origin.
Blocked requests may indicate misconfiguration or active probing:
\napp.use((req, res, next) => {\n if (req.method === 'OPTIONS' || req.headers.origin) {\n const allowed = isAllowedOrigin(req.headers.origin);\n if (!allowed) {\n console.warn('[CORS Rejected]', {\n origin: req.headers.origin,\n method: req.method,\n path: req.path,\n timestamp: new Date().toISOString()\n });\n }\n }\n next();\n});Sec-Fetch-* Headers as a Defense LayerModern browsers send Sec-Fetch-Site, Sec-Fetch-Mode, and Sec-Fetch-Dest headers with every request. These headers are set by the browser and cannot be forged by JavaScript, making them a useful complement to CORS for server-side request validation:
app.use((req, res, next) => {\n const fetchSite = req.headers['sec-fetch-site'];\n // 'same-origin', 'same-site', 'cross-site', or 'none' (direct navigation)\n if (fetchSite === 'cross-site' && req.method !== 'GET') {\n // Consider additional validation for cross-site non-GET requests\n }\n next();\n});This isn’t a CORS replacement, but a complementary layer alongside CSRF tokens and Content Security Policy.
\nOpen the Network tab and look for:
\nOPTIONS requests before your main request (preflight)Access-Control-Allow-Origin on the actual response# Healthy flow\nOPTIONS /api/users 204 2ms (preflight approved)\nPOST /api/users 201 45ms (request succeeded)\n\n# CORS failure\nPOST /api/users --- 0ms (blocked before preflight even sent)\n\nNote: CORS errors in the browser console don’t show the specific cause for security reasons. The Network tab is the only reliable place to see the actual headers exchanged.
\n
curlSimulate a preflight request without a browser:
\ncurl -X OPTIONS https://api.production.com/users \\\n -H \"Origin: https://app.production.com\" \\\n -H \"Access-Control-Request-Method: POST\" \\\n -H \"Access-Control-Request-Headers: Content-Type, Authorization\" \\\n -v 2>&1 | grep -i \"access-control\"Expected output:
\naccess-control-allow-origin: https://app.production.com\naccess-control-allow-methods: GET, POST, PUT, DELETE, OPTIONS\naccess-control-allow-headers: content-type, authorizationProduction CORS failures are often caused by infrastructure, not application code:
\nOPTIONS requestsAlways test with curl directly against your origin server and then again through your CDN to isolate where headers are being dropped.
app.use((req, res, next) => {\n if (req.method === 'OPTIONS' || req.headers.origin) {\n console.log('[CORS Debug]', {\n timestamp: new Date().toISOString(),\n method: req.method,\n path: req.path,\n origin: req.headers.origin,\n requestedMethod: req.headers['access-control-request-method'],\n requestedHeaders: req.headers['access-control-request-headers'],\n });\n }\n next();\n});If production is broken and you need to buy time:
\napp.use((req, res, next) => {\n console.warn('EMERGENCY CORS MODE — REMOVE BEFORE NEXT DEPLOY');\n\n res.header('Access-Control-Allow-Origin', req.headers.origin || '*');\n res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');\n res.header('Access-Control-Allow-Headers', req.headers['access-control-request-headers'] || 'Content-Type, Authorization');\n res.header('Access-Control-Allow-Credentials', 'true');\n res.header('Vary', 'Origin');\n\n if (req.method === 'OPTIONS') return res.sendStatus(204);\n next();\n});Tighten this immediately once the immediate incident is resolved.
\n#!/bin/bash\nAPI_DOMAIN=\"https://api.example.com\"\nFRONTEND_DOMAIN=\"https://app.example.com\"\n\necho \"=== Testing preflight ===\"\ncurl -s -X OPTIONS \"$API_DOMAIN/api/test\" \\\n -H \"Origin: $FRONTEND_DOMAIN\" \\\n -H \"Access-Control-Request-Method: POST\" \\\n -H \"Access-Control-Request-Headers: Content-Type, Authorization\" \\\n -I | grep -i \"access-control\\|vary\"\n\necho \"\"\necho \"=== Testing actual request ===\"\ncurl -s -X GET \"$API_DOMAIN/api/health\" \\\n -H \"Origin: $FRONTEND_DOMAIN\" \\\n -I | grep -i \"access-control\\|vary\"| Header | \nPurpose | \nRequired? | \n
|---|---|---|
Access-Control-Allow-Origin | \nWhich origins can access the response | \nAlways | \n
Access-Control-Allow-Methods | \nAllowed HTTP methods (preflight response) | \nFor preflighted requests | \n
Access-Control-Allow-Headers | \nAllowed request headers (preflight response) | \nFor custom headers | \n
Access-Control-Allow-Credentials | \nWhether cookies/auth are allowed | \nFor credentialed requests | \n
Access-Control-Max-Age | \nHow long to cache the preflight result (seconds) | \nOptional but recommended | \n
Access-Control-Expose-Headers | \nWhich response headers JS can read | \nWhen using non-standard headers | \n
Vary: Origin | \nSignals that responses differ by origin | \nWhen reflecting dynamic origins | \n
Before shipping to production:
\n* origins on authenticated or credentialed endpointsVary: Origin header set on all responses that reflect a dynamic originOPTIONS preflight handled correctly for all relevant routesAccess-Control-Allow-Credentials: true only where cookies/auth are neededSameSite=None; Secure set if using cross-origin session cookiesCORS is not a bug to bypass — it’s a browser security mechanism working exactly as designed. Every CORS error is telling you that a server hasn’t explicitly authorized the cross-origin access being requested.
\nThe key principles:
\nVary. Don’t echo req.headers.origin back without also setting Vary: Origin.OPTIONS requests must be handled for any non-simple cross-origin request.With correct configuration, CORS becomes an ally rather than an obstacle — enforcing the right trust boundaries while letting your legitimate cross-origin traffic flow freely.
\n