CORS Preflight Requests Explained with Practical Examples

In this article, we will explore Cross-Origin Resource Sharing (CORS) and focus on preflight requests. You'll discover what preflight requests are, why they are necessary, and how to implement them effectively in your APIs.
By Jamie

What is CORS?

Cross-Origin Resource Sharing (CORS) is a security feature implemented in web browsers to prevent malicious websites from accessing resources from another domain without permission. When a web application tries to make a request to a different domain (cross-origin), the browser checks if the server allows such requests.

What are Preflight Requests?

A preflight request is a preliminary request sent by the browser to determine whether the actual request is safe to send. This happens when the request method is not a simple method (GET, POST, or HEAD) or when custom headers are used.

When are Preflight Requests Triggered?

  • Non-simple methods: Methods like PUT, DELETE, PATCH, etc.
  • Custom headers: Any headers not considered standard (e.g., Authorization, X-Custom-Header).
  • Content-Type: When using types other than application/x-www-form-urlencoded, multipart/form-data, or text/plain.

Example of a CORS Preflight Request

Let’s look at a practical example to illustrate how preflight requests work.

Scenario

Assume you have a web application hosted on https://example-client.com trying to make a PUT request to an API at https://api.example-server.com/data. The request sends a custom header and uses a non-simple method. Here’s how the preflight request would work:

Step 1: The Preflight Request

Before sending the actual PUT request, the browser sends an OPTIONS request to the server to check if the request is allowed:

OPTIONS /data HTTP/1.1
Host: api.example-server.com
Origin: https://example-client.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: X-Custom-Header

Step 2: Server Response

The server must respond with appropriate CORS headers, indicating whether the actual request is allowed:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example-client.com
Access-Control-Allow-Methods: PUT
Access-Control-Allow-Headers: X-Custom-Header

Step 3: The Actual Request

If the preflight request is successful, the browser sends the actual PUT request:

PUT /data HTTP/1.1
Host: api.example-server.com
Origin: https://example-client.com
X-Custom-Header: value
Content-Type: application/json

{
  "key": "value"

Step 4: Final Server Response

The server responds to the PUT request as follows:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"

Conclusion

Understanding CORS and preflight requests is crucial for developing secure web applications. By implementing proper CORS headers on your server, you ensure that your API can be accessed safely by client applications hosted on different origins.