O que é CORS?

Quando o navegador pode ler outra origem

CORS significa Cross-Origin Resource Sharing, ou compartilhamento de recursos entre origens. É um mecanismo baseado em cabeçalhos HTTP que permite ao servidor autorizar o acesso a respostas por páginas de outras origens. Em chamadas como as feitas com fetch, o navegador confere essa autorização para disponibilizar a resposta ao código da página.

Imagine uma interface publicada em https://app.example.com que consulta https://api.example.com. Como os hosts diferem, as origens também diferem. A API precisa enviar a autorização adequada para que o JavaScript da interface possa ler a resposta.

Uma chamada funcionar no terminal e falhar no navegador pode indicar essa diferença de ambiente. Ferramentas de terminal não aplicam a política de mesma origem da página. Ainda assim, a mensagem de erro precisa ser investigada, pois uma falha no servidor também pode resultar em resposta sem os cabeçalhos esperados.

A autorização aparece na resposta

O cabeçalho Access-Control-Allow-Origin pode conter uma origem específica ou * nas situações permitidas. Ele não aceita uma lista de origens separadas por vírgula. Quando o serviço atende várias origens autorizadas, precisa selecionar o valor adequado para cada resposta.

Access-Control-Allow-Origin: https://app.example.com
Vary: Origin

O exemplo mostra campos de uma resposta cuja autorização varia conforme a origem da chamada. Vary: Origin orienta caches a considerar essa diferença. O servidor deve comparar a origem recebida com suas permissões, sem simplesmente refletir qualquer valor enviado.

O que é preflight

Algumas chamadas exigem uma verificação prévia, chamada de preflight. O navegador envia OPTIONS com a origem, o método pretendido e os cabeçalhos relevantes. A resposta precisa autorizar a combinação antes de a chamada principal seguir.

Um envio JSON com Content-Type: application/json normalmente exige essa verificação em uma chamada entre origens. Outros envios podem acontecer sem preflight, conforme o método e os cabeçalhos utilizados. Para investigar a diferença, compare esses campos na chamada efetiva, sem concluir apenas pela presença de um corpo.

Credenciais exigem configuração específica

Chamadas com cookies precisam respeitar tanto a configuração de credenciais do cliente quanto os atributos e as políticas de cookies. Para expor uma resposta a uma chamada com credenciais, a API deve autorizar a origem explicitamente e enviar Access-Control-Allow-Credentials: true. O curinga * não atende a esse caso.

CORS não autentica a chamada nem concede permissão para executar ações no backend. Também não deve ser tratado como proteção geral contra chamadas de outros programas ou contra CSRF. Esses controles têm responsabilidades próprias.

Como localizar a configuração incorreta

Confira a origem real da página, o preflight quando houver e os cabeçalhos da resposta principal. Respostas de erro e redirecionamentos também podem passar por componentes diferentes, que precisam ser considerados na investigação.

Usar mode: 'no-cors' não libera a leitura do JSON esperado. Esse modo pode produzir uma resposta opaca, indisponível para a interpretação pretendida. O ajuste deve corresponder à arquitetura da integração e à origem web autorizada pelo serviço.

Aplicação na formação

Vibe Coding: Do Zero ao MVP

CORS participa da comunicação quando o frontend precisa ler respostas de uma API em outra origem.

Conhecer a formação →