Custom Headers and Preflight
You'll learn: How adding custom request headers to a fetch() call triggers a CORS preflight check and what server response headers are required to allow them.
Why Custom Headers Matter for CORS
When you send a basic fetch() request, the browser might skip the preflight OPTIONS request if it's a "simple request." But the moment you add custom headers (anything beyond simple headers like Accept, Content-Type, or Accept-Language with limited values), the browser must ask the server for permission first.
Think of it like airport security: carrying standard items (simple headers) lets you pass quickly, but bringing unusual items (custom headers) triggers an additional screening step (preflight).
How Custom Headers Trigger Preflight
When you add a custom header like this:
fetch('https://api.example.com/data', {
headers: {
'X-Custom-Token': 'abc123'
}
});
The browser sends an OPTIONS preflight request first, listing the custom header in Access-Control-Request-Headers. The server must respond with:
Access-Control-Allow-Headers: X-Custom-Token
Only if this header appears in the response (along with Access-Control-Allow-Origin) will the browser proceed with your actual request.
Which Headers Are Safe?
Simple headers that don't trigger preflight include Accept, Accept-Language, and Content-Type (only for application/x-www-form-urlencoded, multipart/form-data, or text/plain). Anything else—authentication tokens, custom API keys, specialized content types—requires preflight approval.
Key Takeaway: Custom request headers automatically trigger a CORS preflight, and the server must explicitly list allowed headers in Access-Control-Allow-Headers for the request to succeed.