What are CORS Safelisted Headers?

A big part of understanding CORS is knowing about CORS safelisted headers. These are the special headers that the browser treats differently when it comes to cross-origin requests. Knowing how they work can save you headaches when debugging CORS issues.

What are CORS Safelisted Headers?

CORS safelisted headers are split into two:

• Safelisted request headers: these allow requests to be made to a different origin without a preflight OPTIONS request.
• Safelisted response headers: these are headers that browsers expose to JavaScript on cross-origin responses by default.

CORS Safelisted Request Headers

CORS safelisted request headers are those that you can include in a cross-origin request without triggering a preflight OPTIONS request. A preflight request is a preliminary request sent by the browser to check if the actual request is allowed by the server. This means you can use them without worrying about the server needing to respond to an OPTIONS request first.

The safelisted request headers are:

• Accept
• Accept-Language
• Content-Language
• Content-Type
• Range

And specifically for Content-Type, the only values that are allowed without triggering a preflight request are:

• application/x-www-form-urlencoded
• multipart/form-data
• text/plain

If you send another value, like application/json, the browser will send a preflight request first to check if the server allows that content type.

CORS Safelisted Response Headers

CORS safelisted response headers, also known as simple response headers, are those that the browser exposes to JavaScript by default. This means you can access them in your JavaScript code without needing to do anything special.

The safelisted response headers are:

• Cache-Control
• Content-Language
• Content-Length
• Content-Type
• Expires
• Last-Modified
• Pragma

By default, other response headers are not exposed to JavaScript. If you want to expose additional headers, the server must include the Access-Control-Expose-Headers header in its response. For example:

Access-Control-Expose-Headers: X-Custom-Header, X-Another-Custom-Header

Conclusion

CORS safelisted headers consist of the safelisted request headers and the safelisted response headers. The request headers are those that you can use in a cross-origin request without triggering a preflight request, while the response headers are those that the browser exposes to JavaScript by default. Understanding these headers is crucial for working with CORS and ensuring that your cross-origin requests work as expected.