CORS

Understand browser security restrictions and learn how to configure Cross-Origin Resource Sharing for secure API access.

CORS stands for Cross-Origin Resource Sharing, and it solves one of the web's most fundamental security challenges. When JavaScript code running on one domain tries to make HTTP requests to another domain, browsers step in with a security policy called the Same-Origin Policy.

This policy exists because without it, malicious websites could silently steal your data from other sites you're logged into. Imagine visiting evil-site.com, which then secretly makes requests to your-bank.com using your logged-in session. CORS prevents this nightmare scenario while still allowing legitimate cross-domain API communication.

But modern web applications need cross-domain requests all the time. Your frontend might run on localhost:3000 during development while hitting an API on localhost:8000. In production, your app might be on app.company.com while your API lives on api.company.com. CORS provides the controlled mechanism that makes this possible.

What Counts as a Different Origin

The protocol matters. https://api.example.com and http://api.example.com are different origins. The domain matters. api.example.com and cdn.example.com are different origins. The port matters. localhost:3000 and localhost:8000 are different origins.

This strictness catches developers off guard. You might think subdomains would be treated as the same origin, but they're not. Moving from HTTP to HTTPS during development breaks things. Even implied ports count — port 80 for HTTP and 443 for HTTPS are still different origins if you specify them explicitly.

Simple vs Preflighted Requests

Simple requests get sent immediately with CORS headers checked afterward. These include GET, HEAD, and POST requests with basic content types like application/x-www-form-urlencoded or text/plain. The browser sends the request and then validates the response headers to decide whether JavaScript should see the result.

Preflighted requests trigger an OPTIONS request first. This happens with PUT, DELETE, PATCH methods, custom headers like Authorization, or JSON content types. The browser asks the server "would you allow this request?" before sending the actual data.

The preflight system exists because servers built before CORS might not expect complex cross-origin requests. A legacy API that never anticipated DELETE requests from web browsers shouldn't suddenly receive them without warning. The preflight gives servers a chance to explicitly opt-in to these interactions.

Essential CORS Headers

Access-Control-Allow-Origin is the most critical header. Set it to * and you allow requests from any domain — convenient for development but dangerous in production. Set it to a specific domain and you lock down access to just that origin. You can only specify one origin per response, not a list.

Access-Control-Allow-Credentials deserves special attention. When set to true, it allows requests to include cookies, authorization headers, and client certificates. But this comes with a restriction — you cannot use a wildcard origin when credentials are allowed. The browser enforces this security rule strictly.

Implementing CORS in Practice

// APIForge API server CORS configuration
const express = require('express');
const cors = require('cors');
const app = express();

const corsOptions = {
  origin: ['https://dashboard.apiforge.com', 'https://app.apiforge.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key'],
  credentials: true,
  maxAge: 86400
};

app.use(cors(corsOptions));

app.get('/api/user/profile', (req, res) => {
  res.json({ id: 1, name: 'Sarah Chen', role: 'Backend Engineer' });
});

This configuration solves the immediate problem but creates new ones for development. Local development typically runs on localhost:3000, which isn't in the allowed origins list. The team needs environment-specific CORS settings that are permissive locally but strict in production.

// Environment-aware CORS configuration
const isDevelopment = process.env.NODE_ENV === 'development';

const corsOptions = {
  origin: function (origin, callback) {
    // Allow requests with no origin (mobile apps, Postman)
    if (!origin) return callback(null, true);
    
    const allowedOrigins = isDevelopment 
      ? ['http://localhost:3000', 'http://localhost:3001']
      : ['https://dashboard.apiforge.com', 'https://app.apiforge.com'];
    
    if (allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('CORS policy violation'));
    }
  },
  credentials: true
};

Common CORS Pitfalls

The "has been blocked by CORS policy" error appears in dozens of variations, but the root cause usually falls into one of five categories. Missing Access-Control-Allow-Origin headers. Mismatched origins in development vs production. Attempting to use wildcards with credentials. Forgetting to handle preflight OPTIONS requests. Trying to read response data from failed CORS requests.

One particularly frustrating scenario happens when your API returns a 500 error but your JavaScript sees a CORS error instead. The server error triggers first, but without proper CORS headers in the error response, the browser blocks access to the error details. Your code can't even read the status code or error message.

The preflight cache creates another class of problems. Browsers cache successful preflight responses based on the Max-Age header, but they don't cache failures. This means a misconfigured server might work intermittently — failing on the first request when preflight is required, then succeeding on subsequent requests when preflight is cached.

Development environments compound these issues. Your localhost frontend making requests to a local API server works fine, but deploying to staging breaks everything because the origins change. HTTPS certificates, subdomain configurations, and port numbers all affect CORS behavior in ways that aren't obvious during local development.

CORS Security Considerations

The wildcard origin (*) disables CORS protection entirely. Any website can make requests to your API, potentially exposing user data or triggering unwanted actions. This might seem acceptable for public APIs, but even read-only endpoints can leak information about API structure, rate limits, or error handling that assists attackers.

Allowing credentials amplifies these risks dramatically. Authenticated requests carry user context — session cookies, authorization tokens, or client certificates that identify specific users. A malicious site that tricks users into visiting while logged into your application could perform actions on their behalf.

The null origin presents a particular challenge. Browsers send Origin: null for requests from file:// URLs, sandboxed iframes, or redirected requests. Some developers allow null origins to support local testing, but this also allows data: URLs and other potentially dangerous contexts.

Subdomain wildcards create another security consideration. While CORS doesn't support subdomain wildcards directly, some developers implement custom logic to allow any subdomain of their domain. This works until someone registers a similar domain name or finds a way to create unauthorized subdomains.

The principle of least privilege applies strongly to CORS configuration. Only allow the specific origins, methods, and headers your application actually needs. Audit these settings regularly as your application evolves and remove any permissions that are no longer required.

Debugging CORS Issues

Browser developer tools reveal the complete CORS conversation. Open the Network tab and look for OPTIONS requests — these are your preflights. Failed preflight requests prevent the actual request from ever being sent. Successful preflights show you exactly which headers the server returned and whether they match what your request needs.

The Console tab shows CORS errors, but these messages are often misleading. A "CORS policy" error might actually be caused by a network failure, a 500 server error, or even a typo in your URL. The Network tab shows what actually happened at the HTTP level.

// APIForge debugging utility for CORS issues
async function debugCorsRequest(url, options = {}) {
  console.log('🔍 CORS Debug Request:', {
    url,
    method: options.method || 'GET',
    headers: options.headers || {},
    credentials: options.credentials || 'same-origin'
  });

  try {
    const response = await fetch(url, options);
    console.log('✅ CORS Success:', {
      status: response.status,
      headers: Object.fromEntries(response.headers.entries())
    });
    return response;
  } catch (error) {
    console.error('❌ CORS Failure:', {
      message: error.message,
      type: error.constructor.name
    });
    throw error;
  }
}

// Test APIForge API endpoint
debugCorsRequest('https://api.apiforge.com/user/profile', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer token123' },
  credentials: 'include'
});

Server-side logging complements client-side debugging. Log incoming OPTIONS requests and the CORS headers you're sending in response. Many CORS issues stem from servers that handle regular requests correctly but fail to process preflight requests or return the wrong headers.

Testing with curl bypasses CORS entirely and helps isolate server-side issues from browser-side restrictions. If curl works but your browser doesn't, you know the problem is in CORS configuration rather than API functionality.

Quiz