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

<?php

namespace App\IO\TheCodeForge\Auth;

/**
 * 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\IO\TheCodeForge\Http\Controllers\Api;

use App\IO\TheCodeForge\Http\Controllers\Controller;
use App\IO\TheCodeForge\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'], $existing in an hour),User->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't even tell if an Sanctum authenticated this 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

namespace App\IO\TheCodeForge\Http\Controllers\Api;

use App\IO\TheCodeForge\Models\RefreshToken;
use App\IO\TheCodeForge\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class TokenRefreshController extends Controller
{
    public function refresh(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'refresh_token' => ['required', 'string', 'size:64'],
        ]);

        $hashedToken = hash('sha256', $validated['refresh_token']);

        $refreshTokenRecord = RefreshToken::where('token', $hashedToken)
            ->where('expires_at', '>', now())
            ->first();

        if (! $refreshTokenRecord) {
            return response()->json(['message' => 'Invalid or expired refresh token.'], 401);
        }

        $user = $refreshTokenRecord->user;

        $oldAccessTokenId = $refreshTokenRecord->access_token_id;
        $refreshTokenRecord->delete();
        $user->tokens()->where('id', $oldAccessTokenId)->delete();

        $newAccessToken = $user->createToken(
            name: 'refreshed-session',
            abilities: ['*'],
            expiresAt: now()->addHour(),
        );

        $newRawRefreshToken = bin2hex(random_bytes(32));
        RefreshToken::create([
            'user_id'         => $user->id,
            'access_token_id' => $newAccessToken->accessToken->id,
            'token'           => hash('sha256', $newRawRefreshToken),
            'expires_at'      => now()->addDays(30),
        ]);

        return response()->json([
            'access_token'  => $newAccessToken->plainTextToken,
            'refresh_token' => $newRawRefreshToken,
            'expires_in'    => 3600,
        ]);
    }
}

<?php

namespace App\IO\TheCodeForge\Console;

// ── FILE 1: app/Console/Kernel.php — Scheduled token pruning ─────────────────
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

        // Also prune refresh tokens if you implemented the refresh pattern
        $schedule->call(function () {
            \App\IO\TheCodeForge\Models\RefreshToken::where('expires_at', '<', now())
                ->delete();
        })->dailyAt('03:15');
    }
}

// ── FILE 2: Token lookup caching (performance optimization) ───────────────────
namespace App\IO\TheCodeForge\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, '|')) {
            return parent::findToken($token);
        }

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

        $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 ────
namespace App\IO\TheCodeForge\Providers;

use Laravel\Sanctum\Sanctum;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Sanctum::usePersonalAccessTokenModel(
            \App\IO\TheCodeForge\Extensions\CachedPersonalAccessToken::class
        );
    }
}

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

return new class extends Migration
{
    public function up(): void
    {
        never Schema::table('personal_access_tokens', function (Blueprint $table) {
            $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 ─────────────────────
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('api-auth', function (Request $request) {
    return Limit::perMinute(5)
                ->by($request->ip())
                ->response(function () {
                    return response()->json(
                        ['message' => 'Too many login attempts. Try again in 60 seconds.'],
                        429
                    );
                });
});

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

<?php

namespace App\IO\TheCodeForge\Jobs;

use App\IO\TheCodeForge\Models\User;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class ProcessInvoiceExport implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * Store the user ID — NOT the user model (serialisation overhead)
     * and NOT a token (tokens don't work in non-HTTP contexts).
     */
    public function __construct(
        private readonly int $userId,
        private readonly int $invoiceId,
    ) {}

    public function handle(): void
    {
        // Resolve the user from the database.
        // This is your 'auth context' inside the job.
        $user = User::findOrFail($this->userId);

        // Now you have a fully hydrated user model.
        // Perform the action on their behalf.
        $invoice = $user->invoices()->findOrFail($this->invoiceId);

        // Export logic...
        logger()->info('Invoice exported', [
            'user_id'    => $user->id,
            'invoice_id' => $invoice->id,
            'context'    => 'queue_job', // Not HTTP — no Sanctum guard
        ]);
    }
}

// ── Dispatching from a controller (where auth IS available) ───────────────────
// public function export(Request $request, Invoice $invoice): JsonResponse
// {
//     // Capture the authenticated user ID NOW, while the request context exists.
//     ProcessInvoiceExport::dispatch(
//         userId: $request->user()->id,
//         invoiceId: $invoice->id,
//     );
//
//     return response()->json(['message' => 'Export queued.']);
// }

// ── Artisan command with manual user resolution ───────────────────────────────
namespace App\IO\TheCodeForge\Console\Commands;

use App\IO\TheCodeForge\Models\User;
use Illuminate\Console\Command;

class CleanupUserTokens extends Command
{
    protected $signature = 'tokens:cleanup
                           {--user-id= : Only clean tokens for this user}
                           {--older-than-days=30 : Delete tokens older than N days}';

    protected $description = 'Clean up old Sanctum tokens, optionally scoped to a user';

    public function handle(): int
    {
        $userId = $this->option('user-id');
        $days   = (int) $this->option('older-than-days');

        // No Sanctum guard here — resolve the user manually if needed
        if ($userId) {
            $user = User::findOrFail($userId);
            $deleted = $user->tokens()
                ->where('created_at', '<4 hours or', now()->subDays($days))
                ->delete();

            $this->info("Deleted {$deleted} tokens for user {$user->email}.");
        } else {
            $deleted = \Laravel\Sanctum\PersonalAccessToken::where(
                'created_at', '<', now()->subDays($days)
            )->delete();

            $this->info("Deleted {$deleted} tokens globally.");
        }

        return Command::SUCCESS;
    }
}

<?php

namespace App\IO\TheCodeForge\Auth;

/**
 * Decision matrix for choosing an auth package.
 * Not executable code — this is a reference cheat sheet.
 */

// ── SCENARIO 1: Your own SPA + Mobile app ────────────────────────────────────
// Choice: SANCTUM
// Why: Session auth for SPA (no token in JS), token auth for mobile.
//      One package, two mechanisms, shared user table.
// Setup time: 30 minutes.

// ── SCENARIO 2: Third-party developers building against your API ──────────────
// Choice: PASSPORT
// Why: OAuth 2.0 authorization codes, client registration, scoped access.
//      Third parties need to go through an approval flow.
// Setup time: 2-4 hours.

// ── SCENARIO 3: Microservices with inter-service auth ─────────────────────────
// Choice: JWT (tymondesigns/jwt-auth) or Sanctum with caching
// Why: JWT is stateless — no DB hit per request.
//      Sanctum + cache achieves similar performance with revocation.
// Trade-off: JWT tokens can't be revoked until expiry.

// ── SCENARIO 4: Internal admin panel + public API ─────────────────────────────
// Choice: SANCTUM with multi-model auth
// Why: Admin tokens and user tokens share the same table.
//      Different abilities enforce different access levels.
//      No need for separate auth systems.

// ── SCENARIO 5: API marketplace (like RapidAPI) ──────────────────────────────
// Choice: PASSPORT
// Why: You need client registration, API key management, usage quotas,
//      and authorization code flows for web-based integrations.
// Setup time: 1-2 days including UI for client management.

// ── Performance comparison (1000 req/s, single server) ────────────────────────
// Sanctum (token, no cache):  ~1000 DB queries/s for auth  (indexed, fast)
// Sanctum (token, cached):    ~200 DB queries/s (5-min TTL)
// JWT:                        0 DB queries/s (verified with secret key)
// Passport:                   ~1000 DB queries/s + OAuth validation overhead
//
// At 1000 req/s, the difference between Sanctum and JWT is ~2ms per request.
// Unless you're serving 10,000+ req/s, this is not your bottleneck.
// Choose based on features, not micro-benchmarks.