This package allow you to keep the session through request/response header. No cookie needed.

1.1.0 2020-05-29 08:09 UTC

This package is auto-updated.

Last update: 2024-06-29 04:58:35 UTC


CSRF verification and session persistent through request/response headers.

This is a lightweight package which allow you to manage a session in a stateless communication (REST/API) when the API domain and main web application domain are different.


  • API hosted under:
  • WEB hosted under:, etc.

In that case you cannot set cookie for different main domains

See why you cannot set cookie under different domain.


You can install the package via composer:

composer require binarcode/laravel-stateless-session


  1. Trigger session, make a GET request to: /api/csrf-header. This will return a header with the session key and an optional header with CSRF token XSRF-TOKEN. The header name could be configured in: stateless.header

  2. Use this header session key/value for every request you want to take care of the session.

  3. If you want to benefit of the CSRF protection of your requests, you should add the follow middlewares to your routes:

use Binarcode\LaravelStatelessSession\Http\Middleware\StatelessStartSession;
use Binarcode\LaravelStatelessSession\Http\Middleware\StatelessVerifyCsrfToken;


You can create a middleware group in your Http\Kernel with these 2 routes as:

protected $middlewareGroups = [
// ...
    'stateless.csrf' => [
// ...

Now the server will return 419 (Page expired code).

Unless you send back a request header named: X-CSRF-TOKEN with the value received by the first GET request in the XSRF-TOKEN header.


  • At this point you have CSRF protection.

  • And you can play with SessionManager and use the session() helper to store/get information (e.g. flash sessions).


The lifetime and other options could be set as before in the session file.

The VerifyHeaderCsrfToken and StartStatelessSession middlewares will inject into headers the session key.

The session key name could be configured in the:

stateless.header => env('STATELESS_HEADER', 'X-STATELESS-HEADER')

Danger: The key name separators should use - not _ according with this.

You can customize the middleware for the csrf-header route. In some cases you may need some custom cors middleware for example:

stateless.middleware => [ 

Real use case

Let's say you want to allow visitors to submit a newsletter form. You want also to protect your API with CSRF.

You can setup a GoogleRecaptcha for that, but that's so annoying.


Vue newsletter page:

// Newsletter.vue
    async created() {
        const response = await axios.get(`${host}/api/csrf-header`);
        this.csrfToken =  response.headers['XSRF-TOKEN'];
        this.sessionKey =  response.headers['LARAVEL-SESSION'];
    methods: {
        async subscribe() {
            await`${host}/api/newsletter`, {email: ''}, {
                headers: { 
                    'LARAVEL-SESSION': this.sessionKey, 
                    'X-CSRF-TOKEN': this.csrfToken


Route::post('api/subscribe', function (Request $request) {

    // at this point the CSRF token is verified 


    return response('', 201)->json();



composer test


Please see CHANGELOG for more information what has changed recently.


Please see CONTRIBUTING for details.


Since the Session Key and X-CSRF-TOKEN could be read by the JavaScript code, that means it's less secure than a usual http-only Cookie. But since we have different domains for the API and WEB, we don't have a way to setup a cookie. You can think of this as of the Bearer token. The security impact is exactly the same.

If you discover any security related issues, please email instead of using the issue tracker.



The MIT License (MIT). Please see License File for more information.