CORS Configuration Guide for REST APIs

A practical guide to understanding and correctly configuring Cross-Origin Resource Sharing for REST APIs. Covers the browser mechanics, common misconfigurations, and production-ready code for Node.js, Python, and Nginx.

How CORS Works: The Browser Flow

When your frontend at https://app.example.com calls an API at https://api.example.com, those are different origins (different subdomain). The browser enforces CORS to protect users.

── Simple Request Flow ──────────────────────────────────────────────
Browser → API:  GET /data
                Origin: https://app.example.com

API → Browser:  200 OK
                Access-Control-Allow-Origin: https://app.example.com
                ✅ Browser allows JavaScript to read the response

── Preflight Flow (non-simple request) ──────────────────────────────
Browser → API:  OPTIONS /data
                Origin: https://app.example.com
                Access-Control-Request-Method: DELETE
                Access-Control-Request-Headers: Authorization

API → Browser:  204 No Content
                Access-Control-Allow-Origin: https://app.example.com
                Access-Control-Allow-Methods: GET, POST, DELETE
                Access-Control-Allow-Headers: Authorization, Content-Type
                Access-Control-Max-Age: 86400   ← cache preflight for 1 day

Browser → API:  DELETE /data/123
                Authorization: Bearer eyJ...
                ✅ Now sends the real request

Express.js Configuration

Simple Single-Origin Setup

import express from 'express';
import cors from 'cors';

const app = express();

// Simple: single trusted origin
app.use(cors({
  origin: 'https://app.yourcompany.com',
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
  exposedHeaders: ['X-Total-Count', 'X-Page'],  // headers JS can read
  maxAge: 86400,  // preflight cache: 24 hours
}));

app.options('*', cors());  // enable pre-flight for all routes

Multi-Origin with Dynamic Allowlist

const ALLOWED_ORIGINS = new Set([
  'https://app.yourcompany.com',
  'https://admin.yourcompany.com',
  'https://staging.yourcompany.com',
  ...(process.env.NODE_ENV === 'development' ? ['http://localhost:3000', 'http://localhost:5173'] : []),
]);

app.use(cors({
  origin: (origin, callback) => {
    // Allow server-to-server requests (no origin header)
    if (!origin) return callback(null, true);

    if (ALLOWED_ORIGINS.has(origin)) {
      callback(null, true);
    } else {
      console.warn(`CORS blocked: ${origin}`);
      callback(new Error(`Origin ${origin} not allowed`));
    }
  },
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
}));

// ⚠️ When using dynamic origin, always add Vary: Origin
app.use((req, res, next) => {
  res.vary('Origin');
  next();
});

FastAPI Configuration

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
import os

app = FastAPI()

ALLOWED_ORIGINS = [
    "https://app.yourcompany.com",
    "https://admin.yourcompany.com",
]

if os.getenv("ENVIRONMENT") == "development":
    ALLOWED_ORIGINS.extend([
        "http://localhost:3000",
        "http://localhost:5173",
    ])

app.add_middleware(
    CORSMiddleware,
    allow_origins=ALLOWED_ORIGINS,        # never use ["*"] with credentials
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
    allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
    expose_headers=["X-Total-Count"],
    max_age=86400,
)

Nginx Configuration

server {
    listen 443 ssl;
    server_name api.yourcompany.com;

    # Map origins to allowed flag
    map $http_origin $cors_origin {
        default                           "";
        "https://app.yourcompany.com"     $http_origin;
        "https://admin.yourcompany.com"   $http_origin;
    }

    location /api/ {
        # Handle preflight
        if ($request_method = OPTIONS) {
            add_header Access-Control-Allow-Origin      $cors_origin always;
            add_header Access-Control-Allow-Credentials true always;
            add_header Access-Control-Allow-Methods    "GET,POST,PUT,DELETE,OPTIONS" always;
            add_header Access-Control-Allow-Headers    "Authorization,Content-Type" always;
            add_header Access-Control-Max-Age          86400 always;
            add_header Vary                            Origin always;
            return 204;
        }

        add_header Access-Control-Allow-Origin      $cors_origin always;
        add_header Access-Control-Allow-Credentials true always;
        add_header Vary                            Origin always;

        proxy_pass http://backend;
    }
}

Common CORS Errors & Fixes