Nov 18, 20265 min read

How to Configure CORS for a Backend API

How browsers decide whether your frontend can call your API, what a preflight request is, why credentials and wildcard origins do not mix, and how to configure CORS in Express, Go and Encore without opening the API to every site.

Illustration for How to Configure CORS for a Backend API

A CORS error is the browser refusing to let JavaScript on one origin read a response from another, and it shows up the first time a frontend on app.example.com calls an API on api.example.com, or a local Vite server on port 5173 calls an API on port 4000.

The tempting fix is Access-Control-Allow-Origin: *, which works until the frontend starts sending cookies, and then fails with a different error that is harder to read.

This guide explains what the browser checks, how preflight requests work, the credential rules, and the configuration for Express, Go and Encore.

CORS configuration at a glance

EncoreExpress with corsGo with rs/cors
Where it livesglobal_cors in encore.appMiddleware optionsHandler wrapper options
DefaultAny origin without credentials; none with credentialsAny origin (*)Any origin (*)
Credentialed originsallow_origins_with_credentials, wildcards allowedorigin list plus credentials: trueAllowedOrigins plus AllowCredentials
Allowed headersAdded from request and response typesYou list themYou list them
Local developmentAll origins allowedSame as production unless you branchSame as production unless you branch

What the browser checks

An origin is scheme, host and port, so http://localhost:5173 and http://localhost:4000 are different origins. For a cross-origin request, the browser sends an Origin header and only exposes the response to JavaScript if the response's Access-Control-Allow-Origin matches. The server still receives and processes the request. CORS protects the user's browser from other sites reading responses, it does not protect your API from being called, which is why curl works when the browser fails.

Preflight requests

Per MDN, "simple" requests (GET, HEAD or POST with only safelisted headers and a form or plain-text content type) go straight through. Anything else, such as a PUT, a JSON body or an Authorization header, triggers a preflight: an OPTIONS request with Access-Control-Request-Method and Access-Control-Request-Headers, which the server must answer with matching Access-Control-Allow-Methods and Access-Control-Allow-Headers before the browser sends the actual request. Access-Control-Max-Age lets the browser cache the preflight, though browsers cap it (Chromium at two hours), so a large value does not mean fewer preflights forever.

Credentials and wildcards

When a request includes cookies or uses fetch(..., { credentials: "include" }), the response must name the exact origin, not *, and must include Access-Control-Allow-Credentials: true. A server that reflects whatever Origin it receives with credentials allowed is equivalent to letting any site make authenticated requests as your users and read the results, so match against an allowlist. When the response varies by origin, also send Vary: Origin so a CDN or shared cache does not serve one origin's headers to another.

Express

import express from "express"; import cors from "cors"; const app = express(); const allowed = new Set(["https://app.example.com", "http://localhost:5173"]); app.use(cors({ origin: (origin, cb) => cb(null, !origin || allowed.has(origin)), // no Origin: same-origin or curl credentials: true, methods: ["GET", "POST", "PUT", "DELETE"], allowedHeaders: ["Content-Type", "Authorization", "Idempotency-Key"], maxAge: 7200, }));

The cors middleware answers preflights automatically when mounted with app.use before your routes, and reflects the matched origin with Vary: Origin.

Go

c := cors.New(cors.Options{ AllowedOrigins: []string{"https://app.example.com", "http://localhost:5173"}, AllowedMethods: []string{"GET", "POST", "PUT", "DELETE"}, AllowedHeaders: []string{"Content-Type", "Authorization", "Idempotency-Key"}, AllowCredentials: true, MaxAge: 7200, }) http.ListenAndServe(":8080", c.Handler(mux))

rs/cors supports wildcard subdomains in AllowedOrigins and an AllowOriginFunc for dynamic checks. Every new custom header the frontend sends has to be added to the allowed list in both examples, which is the most common source of "it worked yesterday" preflight failures.

Common CORS errors

"No 'Access-Control-Allow-Origin' header is present" usually means the origin is not in the allowlist, or the request failed before the CORS middleware ran (a 500 from a proxy, or a route registered before the middleware). "The value of the 'Access-Control-Allow-Origin' header must not be the wildcard '*' when the request's credentials mode is 'include'" means the server returns * for a credentialed request. "Request header field x-foo is not allowed by Access-Control-Allow-Headers" means a custom header is missing from the allowed list. Check the preflight in the browser's network tab, not the main request.

CORS in Encore

Encore

Encore is a backend framework with built-in infrastructure for TypeScript and Go, and CORS is configured once for the whole app in encore.app rather than per server. Per the CORS docs, the default allows unauthenticated requests from any origin, rejects credentialed requests from other origins, and allows all origins in local development. Headers declared on request and response types are added to the allowed and exposed header lists from Encore's parse of your API types, and a new Header<"Idempotency-Key"> field needs no CORS change.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

{ "id": "my-app", "global_cors": { "allow_origins_with_credentials": [ "https://app.example.com", "https://*-preview.example.com" ], "allow_headers": ["X-Request-Source"] } }
// orders/orders.ts import { api, Header } from "encore.dev/api"; interface CreateOrder { idempotencyKey: Header<"Idempotency-Key">; // added to allowed headers automatically sku: string; } export const create = api( { expose: true, auth: true, method: "POST", path: "/orders" }, async (p: CreateOrder): Promise<{ ok: boolean }> => ({ ok: true }), );

A request from https://app.example.com with cookies gets its origin echoed back with credentials allowed; the same request from any other site does not. allow_headers is only needed for headers Encore cannot see in your types, such as those read in raw endpoints. The same settings apply in every environment, with the local exception for development.

A coding agent adding a new header to an endpoint does not have to remember a separate CORS list, which removes a frequent cause of preflight failures in agent-written changes.

Best fit: TypeScript or Go APIs called from browser frontends on other origins, with credentialed origins listed once for the app.

Frequently asked questions

How do I fix a CORS error on my API?

Have the API return Access-Control-Allow-Origin with the frontend's exact origin, answer the OPTIONS preflight with the allowed methods and headers, and, if the request sends cookies or an Authorization header with credentials, also return Access-Control-Allow-Credentials: true. A wildcard origin is not allowed on credentialed requests, and CORS is enforced by the browser, so curl will succeed either way.

How do I configure CORS in Encore?

Set the global_cors key in encore.app. Encore allows unauthenticated requests from any origin by default, rejects credentialed requests from other origins unless you list them in allow_origins_with_credentials (wildcards such as https://*.example.com are supported), and adds headers from your request and response types automatically. Local development allows all origins.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders