Laravel Sanctum API Authentication: Tokens, SPA Sessions & Production Secrets

<?php

/**
 * FILE: Understanding Sanctum's request lifecycle
 * Run: php artisan tinker  (paste each block to inspect)
 *
 * This isn't a controller — it's annotated pseudocode that mirrors
 * what Sanctum's Guard::user() does internally on every request.
 */

// ── Step 1: Sanctum checks if the request is "stateful" ──────────────────────
// config/sanctum.php  →  'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', ...))
// Sanctum compares the request's Origin / Referer header against this list.
$requestOrigin  = 'https://my-spa.com';          // Comes from the browser request
$statefulHosts  = ['my-spa.com', 'localhost'];    // From your .env / config

$isStatefulRequest = in_array(
    parse_url($requestOrigin, PHP_URL_HOST),
    $statefulHosts
);

if ($isStatefulRequest) {
    // ── Path A: SPA Session Auth ──────────────────────────────────────────
    // Sanctum delegates entirely to the 'web' guard.
    // The session cookie (laravel_session) carries the user ID.
    // No token is involved. CSRF protection via X-XSRF-TOKEN header.
    echo "Authenticating via session cookie (web guard delegation)" . PHP_EOL;
} else {
    // ── Path B: Token Auth ────────────────────────────────────────────────
    // Sanctum reads the raw token from the Authorization header.
    $rawToken = 'your-app|AbCdEf123456...'; // Format: {tokenId}|{rawSecret}

    // Splits on the pipe to get the token ID (avoids full-table scans).
    [$tokenId, $rawSecret] = explode('|', $rawToken, 2);

    // Hashes the secret portion with SHA-256.
    $hashedSecret = hash('sha256', $rawSecret);

    // Queries: SELECT * FROM personal_access_tokens WHERE id = ? AND token = ?
    // This single indexed query is why Sanctum performs well under load.
    echo "Looking up token ID: {$tokenId} with hash: {$hashedSecret}" . PHP_EOL;

    // If found, Sanctum calls $tokenModel->tokenable to get the User via
    // a polymorphic relationship — so one token table serves ALL model types.
    echo "User resolved via polymorphic tokenable() relationship" . PHP_EOL;
}

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

class ApiAuthController extends Controller
{
    /**
     * Register a new user and immediately issue a scoped token.
     * Real-world: a mobile app's "Sign Up" screen calls this.
     */
    public function register(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'name'     => ['required', 'string', 'max:255'],
            'email'    => ['required', 'email', 'unique:users'],
            'password' => ['required', 'string', 'min:12', 'confirmed'],
            'device_name' => ['required', 'string', 'max:100'], // e.g. "iPhone 15 Pro"
        ]);

        $newUser = User::create([
            'name'     => $validated['name'],
            'email'    => $validated['email'],
            // Always hash — never store plain text passwords
            'password' => Hash::make($validated['password']),
        ]);

        // createToken() returns a NewAccessToken object.
        // The PLAIN TEXT token is only available RIGHT NOW via ->plainTextToken.
        // After this response, it cannot be retrieved again — store it client-side.
        $newAccessToken = $newUser->createToken(
            name: $validated['device_name'],          // Human-readable label
            abilities: ['invoices:read', 'profile:update'], // Scope this token
            expiresAt: now()->addDays(30)             // Expires in 30 days
        );

        return response()->json([
            'user'  => $newUser->only(['id', 'name', 'email']),
            // Send this ONCE. The client must store it securely (Keychain, Keystore)
            'token' => $newAccessToken->plainTextToken,
            'abilities' => $newAccessToken->accessToken->abilities,
        ], 201);
    }

    /**
     * Login: validate credentials, issue a new token per device.
     * Using per-device tokens means users can revoke individual sessions.
     */
    public function login(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'email'       => ['required', 'email'],
            'password'    => ['required', 'string'],
            'device_name' => ['required', 'string', 'max:100'],
        ]);

        $existingUser = User::where('email', $validated['email'])->first();

        // Deliberate: we give the same error for 'user not found' AND 'wrong password'.
        // This prevents user enumeration attacks.
        if (! $existingUser || ! Hash::check($validated['password'], $existingUser->password)) {
            throw ValidationException::withMessages([
                'email' => ['The credentials you provided do not match our records.'],
            ]);
        }

        // Optional: revoke all tokens for this device name before issuing a new one.
        // Prevents token accumulation if users log in repeatedly on the same device.
        $existingUser->tokens()
            ->where('name', $validated['device_name'])
            ->delete();

        $freshToken = $existingUser->createToken(
            name: $validated['device_name'],
            abilities: ['*'], // Wildcard = all abilities (use sparingly)
        );

        return response()->json([
            'token' => $freshToken->plainTextToken,
        ]);
    }

    /**
     * Logout: revoke ONLY the token used for this request.
     * The user stays logged in on all other devices.
     */
    public function logout(Request $request): JsonResponse
    {
        // currentAccessToken() returns the PersonalAccessToken model
        // that Sanctum authenticated this specific request with.
        $request->user()->currentAccessToken()->delete();

        return response()->json([
            'message' => 'This device has been logged out successfully.',
        ]);
    }

    /**
     * Logout from ALL devices — nuclear option.
     * Use for 'I lost my phone' or 'Suspect unauthorized access' scenarios.
     */
    public function logoutAllDevices(Request $request): JsonResponse
    {
        // tokens() is the HasMany relationship to personal_access_tokens.
        // This deletes every row belonging to this user.
        $revokedCount = $request->user()->tokens()->delete();

        return response()->json([
            'message' => "Logged out from {$revokedCount} device(s).",
        ]);
    }
}

// ── routes/api.php ────────────────────────────────────────────────────────────
// Route::post('/register',          [ApiAuthController::class, 'register']);
// Route::post('/login',             [ApiAuthController::class, 'login']);
// Route::middleware('auth:sanctum')->group(function () {
//     Route::post('/logout',         [ApiAuthController::class, 'logout']);
//     Route::post('/logout-all',     [ApiAuthController::class, 'logoutAllDevices']);
//     Route::get('/profile',         [ProfileController::class, 'show']);
// });

// ── How to check token abilities inside a protected controller ────────────────
// public function show(Request $request): JsonResponse
// {
//     // Throws 403 automatically if the token lacks this ability
//     $request->user()->tokenCan('invoices:read') || abort(403, 'Token cannot read invoices');
//
//     // Or use the ability middleware on the route:
//     // Route::get('/invoices', ...)->middleware('ability:invoices:read');
// }

<?php
// ── FILE 1: config/sanctum.php (key section) ─────────────────────────────────
return [
    /*
     * Stateful domains: requests from these origins authenticate via session.
     * Add EVERY domain your SPA can be served from, including ports.
     * Production: 'my-spa.com'
     * Development: 'localhost:3000', 'localhost:5173' (Vite default)
     *
     * In .env: SANCTUM_STATEFUL_DOMAINS=my-spa.com,localhost:3000
     */
    'stateful' => explode(',', env(
        'SANCTUM_STATEFUL_DOMAINS',
        sprintf(
            '%s%s',
            'localhost,localhost:3000,localhost:5173,127.0.0.1,127.0.0.1:8000',
            Sanctum::currentApplicationUrlWithPort()
        )
    )),

    /*
     * Token expiration: null means tokens live forever.
     * In production, always set this. 525600 = 1 year in minutes.
     * Expired tokens are NOT auto-deleted — run the pruning command.
     */
    'expiration' => env('SANCTUM_TOKEN_EXPIRY_MINUTES', null),

    /*
     * Guard: which auth guard Sanctum will try for stateful sessions.
     * Keep this as 'web' unless you have a custom session guard.
     */
    'guard' => ['web'],

    'middleware' => [
        // This middleware must be registered for SPA auth to work.
        // It initializes the session and validates the CSRF token.
        'authenticate_session' => Laravel\Sanctum\Http\Middleware\CheckAbilities::class,
        'encrypt_cookies'      => Illuminate\Cookie\Middleware\EncryptCookies::class,
        'validate_csrf_token'  => Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
    ],
];

// ── FILE 2: config/cors.php ───────────────────────────────────────────────────
return [
    'paths' => [
        'api/*',
        'sanctum/csrf-cookie', // MUST include this — it seeds the XSRF-TOKEN cookie
        'login',
        'logout',
    ],

    'allowed_methods' => ['*'],

    'allowed_origins' => [
        env('FRONTEND_URL', 'http://localhost:3000'),
        // Never use '*' here — browsers won't send credentials with wildcard origins
    ],

    'allowed_origins_patterns' => [],
    'allowed_headers'          => ['*'],
    'exposed_headers'          => [],
    'max_age'                  => 0,

    /*
     * THIS IS THE CRITICAL SETTING.
     * 'supports_credentials' => true tells the browser:
     * "yes, include cookies and auth headers in cross-origin requests".
     * Your frontend ALSO needs withCredentials: true on every request.
     */
    'supports_credentials' => true,
];

// ── FILE 3: app/Http/Kernel.php — Register Sanctum's stateful middleware ─────
// Inside the 'api' middleware group:
protected $middlewareGroups = [
    'api' => [
        // This middleware intercepts stateful requests BEFORE auth runs.
        // Without it, cookie auth on the 'api' group is silently broken.
        \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        'throttle:api',
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ],
];

// ── FILE 4: Frontend (JavaScript / Axios) ─────────────────────────────────────
/*
import axios from 'axios';

// Configure Axios ONCE at app startup — every request will carry cookies.
axios.defaults.baseURL = 'https://api.myapp.com';
axios.defaults.withCredentials = true; // <── non-negotiable for SPA cookie auth

async function loginUser(email, password) {
    // Step 1: Fetch the CSRF cookie. Sanctum sets XSRF-TOKEN cookie.
    // Axios automatically reads this cookie and sends it as X-XSRF-TOKEN on POST.
    await axios.get('/sanctum/csrf-cookie');

    // Step 2: Post credentials to the standard web login route.
    // This sets the laravel_session cookie.
    await axios.post('/login', { email, password });

    // Step 3: All subsequent requests are automatically authenticated.
    const profile = await axios.get('/api/user');
    return profile.data;
}
*/

<?php

// ── FILE 1: app/Console/Kernel.php — Scheduled token pruning ─────────────────
namespace App\Console;

use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;

class Kernel extends ConsoleKernel
{
    protected function schedule(Schedule $schedule): void
    {
        // Prune tokens that expired more than 24 hours ago.
        // Runs every day at 3:00 AM — low traffic window.
        $schedule->command('sanctum:prune-expired --hours=24')
                 ->dailyAt('03:00')
                 ->onOneServer()         // Prevents duplicate runs in multi-server setups
                 ->runInBackground();    // Doesn't block other scheduled tasks
    }
}

// ── FILE 2: Token lookup caching (performance optimization) ───────────────────
// By default, every authenticated request hits personal_access_tokens.
// At 1000 req/s this is 1000 DB queries/s just for auth.
// Solution: Cache the token model for the duration of the request — or longer.

// In a Service Provider or custom Guard extension:
namespace App\Extensions;

use Illuminate\Support\Facades\Cache;
use Laravel\Sanctum\PersonalAccessToken;

class CachedPersonalAccessToken extends PersonalAccessToken
{
    /**
     * Override Sanctum's token finder to cache the result.
     * Laravel Sanctum calls PersonalAccessToken::findToken($rawToken) internally.
     * By extending the model and registering it, we inject caching transparently.
     */
    public static function findToken(string $token): ?static
    {
        if (! str_contains($token, '|')) {
            // Tokens without the pipe are legacy plain hashes — don't cache them
            return parent::findToken($token);
        }

        [$tokenId] = explode('|', $token, 2);

        // Cache key is based on token ID — safe because we still hash-verify below.
        $cacheKey = "sanctum_token_{$tokenId}";

        // Cache for 5 minutes. Short enough that revoked tokens expire quickly.
        // After logout (token deletion), the cached record will cause a 401
        // only if someone uses the revoked token within the 5-min window —
        // acceptable trade-off for most apps. Use 0 TTL for banking/medical.
        return Cache::remember($cacheKey, now()->addMinutes(5), function () use ($token) {
            return parent::findToken($token);
        });
    }

    /**
     * When a token is deleted (logout), bust the cache immediately.
     */
    protected static function boot(): void
    {
        parent::boot();

        static::deleted(function (self $accessToken) {
            Cache::forget("sanctum_token_{$accessToken->id}");
        });
    }
}

// ── FILE 3: AppServiceProvider.php — Tell Sanctum to use your cached model ────
use Laravel\Sanctum\Sanctum;

public function boot(): void
{
    // One line — Sanctum will now call CachedPersonalAccessToken::findToken()
    Sanctum::usePersonalAccessTokenModel(
        \App\Extensions\CachedPersonalAccessToken::class
    );
}

// ── FILE 4: Database migration — Add missing index for multi-model auth ───────
// php artisan make:migration add_tokenable_index_to_personal_access_tokens
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('personal_access_tokens', function (Blueprint $table) {
            // Composite index on the polymorphic columns.
            // Critical when you have multiple tokenable model types.
            // Without this, every auth query does a full-table scan on tokenable columns.
            $table->index(
                ['tokenable_type', 'tokenable_id'],
                'pat_tokenable_type_tokenable_id_index'
            );
        });
    }

    public function down(): void
    {
        Schema::table('personal_access_tokens', function (Blueprint $table) {
            $table->dropIndex('pat_tokenable_type_tokenable_id_index');
        });
    }
};

// ── FILE 5: routes/api.php — Rate limiting auth endpoints ─────────────────────
// Register a named limiter in RouteServiceProvider or a Service Provider:
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('api-auth', function (Request $request) {
    // Throttle login attempts: 5 per minute per IP address.
    // Brute-force protection without a full auth shield package.
    return Limit::perMinute(5)
                ->by($request->ip())
                ->response(function () {
                    return response()->json(
                        ['message' => 'Too many login attempts. Try again in 60 seconds.'],
                        429
                    );
                });
});

// Apply the limiter to auth routes:
Route::middleware('throttle:api-auth')->group(function () {
    Route::post('/login',    [ApiAuthController::class, 'login']);
    Route::post('/register', [ApiAuthController::class, 'register']);
});