Maintenance Mode with Secret Code on headless API?

The issue you're facing is indeed a common challenge when dealing with headless APIs in Laravel. Since the secret code mechanism in Laravel's maintenance mode primarily works through browser cookies, it doesn't align well with typical API usage where interactions are done via HTTP headers instead of cookies.

However, you can implement a custom solution to allow bypassing maintenance mode in your API by using a specific HTTP header. Here’s how you can achieve this:

1. Create a Middleware: You'll need to create a custom middleware that checks for a specific HTTP header and bypasses the maintenance mode if the header contains the correct secret code.

2. Register the Middleware: After creating the middleware, you must register it in your kernel so that it runs before the maintenance mode check.

Here's a step-by-step guide to implementing this:

Step 1: Create Middleware

Create a new middleware named CheckForMaintenanceModeWithSecret:

php artisan make:middleware CheckForMaintenanceModeWithSecret

In the middleware, check for a specific header, say X-MAINTENANCE-BYPASS, and compare its value with a secret stored in your environment file:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Foundation\Http\Exceptions\MaintenanceModeException;

class CheckForMaintenanceModeWithSecret
{
    public function handle($request, Closure $next)
    {
        if (app()->isDownForMaintenance()) {
            $secret = $request->header('X-MAINTENANCE-BYPASS');
            $allowedSecret = env('MAINTENANCE_MODE_SECRET');

            if ($secret !== $allowedSecret) {
                throw new MaintenanceModeException();
            }
        }

        return $next($request);
    }
}

Step 2: Register Middleware

Open your app/Http/Kernel.php file and register the middleware in the $middlewarePriority array. It's important to place it before CheckForMaintenanceMode to ensure it runs first:

protected $middlewarePriority = [
    \App\Http\Middleware\CheckForMaintenanceModeWithSecret::class,
    \Illuminate\Foundation\Http\Middleware\CheckForMaintenanceMode::class,
    // other middleware...
];

Step 3: Set Your Secret

In your .env file, set the MAINTENANCE_MODE_SECRET to a secure value:

MAINTENANCE_MODE_SECRET=your_secret_code_here

Using the API in Maintenance Mode

When making API requests during maintenance mode, include the X-MAINTENANCE-BYPASS header with the correct secret:

curl -H "X-MAINTENANCE-BYPASS: your_secret_code_here" https://yourapi.com/endpoint

This setup allows your headless API to support a secret code bypass for maintenance mode, aligning with the stateless nature of APIs and avoiding reliance on cookies.