what is the difference between X-XSRF-TOKEN and X-CSRF-TOKEN?

what is the difference between X-XSRF-TOKEN and X-CSRF-TOKEN?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

What Is the Difference Between X-XSRF-TOKEN and X-CSRF-TOKEN?

When developers implement Cross-Site Request Forgery (CSRF) protection, they often encounter two distinct header names: X-XSRF-TOKEN and X-CSRF-TOKEN. While both serve the ultimate goal of verifying user intent, their underlying mechanisms and typical use cases differ significantly. Confusing them can lead to broken authentication flows or incomplete security implementations.

The Mechanism Behind X-XSRF-TOKEN

The X-XSRF-TOKEN header is designed for a specific scenario involving SameSite=None cookies that lack the Secure flag, or more commonly in modern frameworks, when using JavaScript to extract a CSRF token from a cookie and attaching it to AJAX requests.

In this pattern, the server stores a unique token in a secure, HttpOnly cookie (e.g., csrf_token). Because JavaScript cannot read the contents of HttpOnly cookies for security reasons, the client-side script must rely on a separate mechanism to retrieve this value. The standard approach involves creating a non-cors-enabled endpoint that returns only the CSRF token value as plain text, or reading it from a dedicated cookie if SameSite is relaxed.

The client then places this retrieved value into the X-XSRF-TOKEN header on subsequent requests to protected endpoints. The server validates the request by comparing the incoming header value against the one stored in the user's session or memory cache. This two-step process—storing the token in a cookie and sending it via a header—is crucial for same-origin AJAX calls where the browser automatically attaches the cookie but does not know to include the token in the header unless explicitly told to do so by JavaScript logic.

The Role of X-CSRF-TOKEN

The X-CSRF-TOKEN header is generally treated as a generic name for carrying CSRF protection data. In many frameworks, including Laravel, this header is often populated directly from the request parameters or form fields rather than being strictly tied to the cookie-reading logic used by X-XSRF-TOKEN.

When using standard HTML forms with traditional POST submissions, the browser handles CSRF tokens automatically if they are present in hidden input fields (<input type="hidden" name="_token">). In these cases, frameworks often intercept this token and promote it to the X-CSRF-TOKEN header for API consistency. However, if you are building an application that relies entirely on JavaScript-driven forms or API calls without relying on the automatic cookie attachment mechanism, you might populate the X-CSRF-TOKEN header directly from a value stored in local storage, session storage, or a meta tag injected by the server.

Implementation Trade-offs and Decisions

The choice between these headers often depends on your framework's configuration and the nature of your frontend. If you are working with Laravel, the framework provides helper methods to handle this complexity. You can retrieve the token from the request using csrf_token() and assign it to a header like X-CSRF-TOKEN for API routes.

// Example in Laravel Blade template
<meta name="csrf-token" content="{{ csrf_token() }}">
<script>
    document.head.insertAdjacentHTML('beforeend', 
        '<meta name="csrf-token" content="{{ csrf_token() }}">'
    );
</script>

Alternatively, you can configure Laravel to automatically read the X-XSRF-TOKEN header if it exists, falling back to the _token parameter or cookie. This flexibility allows you to switch between traditional form-based submissions and modern AJAX interactions without changing your validation logic significantly.

A common pitfall occurs when developers assume these headers are interchangeable without understanding how the server validates them. If your application expects the token to come from a specific source (e.g., a signed cookie) but receives it via a header derived from local storage, the validation might fail if the sources aren't synchronized. Always ensure that the strategy for generating and storing the token matches the strategy for extracting and validating it on the server side.

When to Use Which

Use X-XSRF-TOKEN when your architecture explicitly separates the cookie (for secure transport) from the header value (for AJAX transmission), often relying on a dedicated endpoint to fetch the token value into JavaScript variables. This is common in setups where you cannot use HttpOnly cookies for the token itself or need to bypass browser restrictions for specific cross-origin scenarios.

Use X-CSRF-TOKEN when your framework automatically promotes form tokens or meta tag values to headers, or when you are building an API where the token is stored in a client-side variable (like local storage) and manually attached to requests. The distinction is less about the header name itself and more about the lifecycle of the token: whether it is fetched from a cookie via a specific mechanism (X-XSRF-TOKEN) or promoted directly from form/metadata inputs (X-CSRF-TOKEN).

For robust CSRF protection, focus on ensuring that every state-changing request (POST, PUT, DELETE) includes a valid token, regardless of the header name used. Frameworks like Laravel simplify this by allowing you to define middleware that accepts either header format or standard POST parameters, reducing the cognitive load of managing these differences manually.

Our network