FastAPI CORSMiddleware: allow_credentials Without a Wildcard

Failure symptom:

Access to fetch at 'https://api.orbitmail.dev/v1/messages' from origin
'https://console.orbitmail.dev' has been blocked by CORS policy: The value of
the 'Access-Control-Allow-Origin' header in the response must not be the
wildcard '*' when the request's credentials mode is 'include'.

The maddening part is that this error is usually intermittent. The same page, the same endpoint, the same build: it works right after signing in, then fails in an incognito window or on the very first load after a cookie expiry. Nothing in your code changed between the two calls.

Root Cause

The configuration that produces the intermittent behaviour is allow_origins=["*"] combined with allow_credentials=True. Starlette’s CORSMiddleware — which FastAPI re-exports as fastapi.middleware.cors.CORSMiddleware — precomputes a static header set at startup. When every origin is allowed, that static set contains Access-Control-Allow-Origin: *. On the way out, the middleware only replaces that wildcard with the caller’s exact origin if the request carried a Cookie header. A browser request made with credentials: "include" but an empty cookie jar sends no Cookie header at all, so the wildcard survives — and the browser refuses a wildcard whenever the credentials mode is include, exactly as the WHATWG Fetch Standard requires. The preflight takes a different code path and does echo the origin, so the OPTIONS request passes and only the real request is blocked, which is why the Network panel shows a green preflight above a red POST.

This page is part of Framework CORS Middleware Configuration, which covers the middleware layer where most production CORS policy actually lives.

The divergence between the two round trips is worth tracing once, because it explains every “but the preflight is fine!” report you will ever get about a FastAPI service:

Prerequisite State

Before applying the fix, confirm the following:

• FastAPI is installed with a recent Starlette (pip show starlette), and the service is served by Uvicorn or Hypercorn.
• The browser code sends credentials: "include" (fetch) or withCredentials = true (XHR/axios) — otherwise you do not need allow_credentials at all and should turn it off.
• The session cookie itself is issued with SameSite=None; Secure, or the browser will not attach it to a cross-site request no matter what CORS says. The trade-offs are covered in SameSite=None vs CORS Credentials: The Tradeoffs.
• You know the exact origin strings the frontend is served from, scheme and port included. https://console.orbitmail.dev and https://console.orbitmail.dev:443 are the same origin; http://localhost:5173 and http://127.0.0.1:5173 are not, as Why localhost and 127.0.0.1 Are Different Origins explains.

Step-by-Step Fix

Step 1 — Replace the wildcard with an explicit allowlist

Name every origin. Load the list from settings so staging and production differ by configuration rather than by code.

# app/settings.py
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    # Comma-separated in the environment, e.g.
    # CORS_ORIGINS="https://console.orbitmail.dev,https://admin.orbitmail.dev"
    cors_origins: str = "http://localhost:5173"

    @property
    def cors_origin_list(self) -> list[str]:
        return [o.strip() for o in self.cors_origins.split(",") if o.strip()]


settings = Settings()

# app/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from app.settings import settings

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.cors_origin_list,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PATCH", "DELETE", "OPTIONS"],
    allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
    expose_headers=["X-Request-ID", "X-RateLimit-Remaining"],
    max_age=600,
)

With a concrete list in place, the middleware compares the incoming Origin against it with an exact string match and echoes the matched value — the same discipline described in Dynamic Origin Validation Patterns. It also adds Vary: Origin automatically once it is echoing rather than wildcarding, which keeps shared caches honest.

Every keyword argument above maps to exactly one response header, and knowing the mapping turns header debugging into a one-line configuration edit:

Step 2 — Add CORSMiddleware last so it runs first

add_middleware inserts each layer at the top of the stack, so the last call wraps everything before it. That inversion is the second-most-common FastAPI CORS bug: an authentication middleware registered after CORSMiddleware becomes the outermost layer, sees a credential-free OPTIONS preflight, and returns 401 before the CORS layer ever runs.

# app/main.py — correct order
app = FastAPI()

app.add_middleware(RequestIDMiddleware)        # innermost at runtime
app.add_middleware(SessionAuthMiddleware)      # runs second
app.add_middleware(CORSMiddleware, **cors_kwargs)  # added last -> runs FIRST

If SessionAuthMiddleware must stay outermost for some other reason, it has to let the preflight through itself:

class SessionAuthMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        if request.method == "OPTIONS":
            return await call_next(request)   # never authenticate a preflight
        ...

The two orderings look almost identical in the source file and behave completely differently at runtime:

Step 3 — Declare the header contract instead of inheriting defaults

Starlette’s defaults are deliberately narrow: allow_methods defaults to ("GET",) and allow_headers to the empty tuple, on top of the CORS-safelisted request headers. A POST of JSON with a bearer token matches neither default, so the preflight fails on both counts. The table below is the full parameter surface.

Two details in that table cause real outages. First, allow_headers=["*"] under credentials reflects whatever the browser asked for, which quietly defeats the point of listing headers at all — enumerate them instead. Second, max_age is a request, not a promise: Chromium caps a preflight entry at 7200 seconds regardless of what you send, as How to Set Access-Control-Max-Age Effectively sets out.

Step 4 — Make the browser call match

const res = await fetch("https://api.orbitmail.dev/v1/messages", {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
    "X-Request-ID": crypto.randomUUID(),
  },
  body: JSON.stringify({ subject: "Weekly digest" }),
});

X-Request-ID is not safelisted, so this call preflights. Because the header is named in both allow_headers and expose_headers, the preflight passes and the response copy of the header is readable from JavaScript.

Verification

Run the preflight and the actual request separately — they exercise different branches of the middleware, and only checking one is how the wildcard bug survives review.

# 1) Preflight: expect 200, an exact origin echo, and vary: origin
curl -sS -i -X OPTIONS https://api.orbitmail.dev/v1/messages \
  -H 'Origin: https://console.orbitmail.dev' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type,x-request-id' \
  | grep -iE '^(HTTP|access-control|vary)'

# 2) Actual request WITHOUT a cookie: the echo must still be exact, never *
curl -sS -i -X POST https://api.orbitmail.dev/v1/messages \
  -H 'Origin: https://console.orbitmail.dev' \
  -H 'Content-Type: application/json' -d '{"subject":"probe"}' \
  | grep -iE '^(access-control|vary)'

# 3) An origin that is not on the list must produce no access-control headers
curl -sS -i -X OPTIONS https://api.orbitmail.dev/v1/messages \
  -H 'Origin: https://console.orbitmail.dev.attacker.example' \
  -H 'Access-Control-Request-Method: POST' | grep -ci access-control-allow-origin

Work through the checklist before closing the ticket:

• The preflight returns 200 and access-control-allow-origin is the literal console origin, not *.
• access-control-allow-credentials: true is present on both the preflight and the actual response.
• vary: origin appears on both responses so a shared cache cannot cross-serve them.
• Probe 2 — deliberately cookie-free — still echoes the exact origin.
• Probe 3 prints 0; the lookalike origin gets nothing.
• In DevTools, Network, the OPTIONS row and the POST row are both 200, and the POST response headers show one access-control-allow-origin.
• In DevTools, Application, Cookies, the session cookie shows SameSite=None and Secure; without those the browser never attaches it.
• Restart Uvicorn and repeat probe 1 — a stale preflight cache can mask a broken configuration for max_age seconds. The techniques in Simulating a Preflight with curl -X OPTIONS bypass that cache entirely.

Security Boundary Note

Do not reach for allow_origin_regex=".*" as a shortcut once you discover the wildcard is refused. It produces exactly the open policy the browser was protecting you from, only through a route the linters do not recognise: every origin on the internet matches, credentials are attached, and any page the victim visits can read authenticated responses from your API. If preview deployments genuinely need dynamic origins, anchor the pattern and escape the dots — r"https://[a-z0-9-]+\.preview\.orbitmail\.dev" — and never combine an unanchored pattern with allow_credentials=True. The failure modes of the permissive end of this spectrum are catalogued in Wildcard CORS Risks and Safe Origin Allowlisting.

Common Mistakes

FAQ