Como você configura CORS em FastAPI?

Question

Accepted Answer

**CORS** (Cross-Origin Resource Sharing) é um mecanismo de segurança do navegador que controla se uma página web de uma **origem** pode chamar sua API em uma origem diferente. FastAPI a configura com o **`CORSMiddleware`** integrado. Você enfrentará CORS sempre que um frontend em um domínio/porta diferente chamar sua API.

## O problema que CORS resolve

```text
A React app at http://localhost:3000 calling an API at http://localhost:8000 is
CROSS-ORIGIN (different port). The BROWSER blocks the response unless the API
sends CORS headers permitting that origin.
(origin = scheme + host + port)
```

## Configurando CORSMiddleware

```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com", "http://localhost:3000"],  # ALLOWLIST of origins
    allow_credentials=True,         # allow cookies/auth (requires specific origins, not "*")
    allow_methods=["*"],             # or ["GET", "POST", ...]
    allow_headers=["*"],
)
```

O middleware adiciona os headers de resposta CORS necessários, informando ao navegador quais origens, métodos e headers são permitidos. O navegador aplica essas regras.

## Segurança: restrinja origens (não use "*")

```python
# ❌ allowing all origins — convenient but insecure for credentialed/private APIs
allow_origins=["*"]
# ✅ restrict to your known frontend origins (an allowlist)
allow_origins=["https://app.example.com"]
# NOTE: allow_credentials=True is INCOMPATIBLE with allow_origins=["*"]
```

Em produção, **restrinja `allow_origins` a uma lista permitida** em vez de `*`. Além disso, permitir credenciais (cookies/autenticação) requer origens específicas — o wildcard não é permitido com credenciais.

## Uma concepção-chave equivocada

```text
CORS is enforced by the BROWSER, not the server. It does NOT protect your API from
non-browser clients (curl, Postman, other servers) — those ignore CORS entirely.
CORS only governs what browser JavaScript from other origins may do.
```

## Por que isso importa

CORS é um dos maiores obstáculos no desenvolvimento web — quase toda configuração frontend-para-API o enfrenta (especialmente no desenvolvimento local com portas diferentes, e em produção com um domínio de frontend separado), portanto saber como configurá-lo com o `CORSMiddleware` do FastAPI é conhecimento prático e frequentemente necessário.

Compreender *por que* ele existe (segurança same-origin do navegador), como o servidor opta por participar via headers de resposta e como configurá-lo (origens permitidas, métodos, headers, credenciais) é necessário para conectar frontends a APIs FastAPI sem que as requisições sejam bloqueadas.

Igualmente importante é configurá-lo **com segurança** — restringindo `allow_origins` a uma lista permitida específica em vez da permissiva `*` (e entendendo que credenciais são incompatíveis com o wildcard) — e compreendendo a concepção-chave equivocada crucial de que **CORS é um mecanismo do navegador, não autorização de API** (não protege contra clientes não-navegador).

Saber como configurar CORS corretamente e com segurança é conhecimento importante do dia a dia para qualquer API FastAPI consumida por um frontend web.