Laravel Sanctum for PHP: Complete Guide to API Tokens and SPA Authentication

1. What It Is and Why You Need It

Laravel Sanctum is a lightweight authentication library for the PHP framework Laravel, designed for managing API tokens and single-page applications (SPA). Developed by Taylor Otwell and the Laravel team, Sanctum provides a simple yet powerful way to protect API routes, allowing developers to quickly implement authentication without the complex setup typical of heavier solutions like Passport (OAuth2).

Sanctum's main task is to solve two key problems of modern web development: authentication for SPAs (Single Page Applications) running on the same domain as the backend, and issuing API tokens for mobile applications or third-party services. Unlike Passport, Sanctum does not use the full OAuth2 protocol, making it an ideal choice for projects that do not require a complex access delegation system. It uses Laravel sessions for SPA authentication and simple HMAC-based tokens for the API.

The library is included in the standard Laravel 8 and higher distribution, making it available "out of the box." Sanctum is especially useful for startups, small teams, and projects where development speed and minimal dependencies are important. It automatically manages token expiration, supports "abilities" for fine-grained access control, and integrates easily with Laravel Fortify, Breeze, or Jetstream.

2. Installation

Laravel Sanctum is installed via Composer, the standard package manager for PHP. Make sure you have PHP 8.0 or higher and Laravel 8.x/9.x/10.x/11.x installed.

The exact command for installation:

composer require laravel/sanctum

After installation, you need to publish the configuration file and database migrations:

php artisan vendor:publish --provider="Laravel\\Sanctum\\SanctumServiceProvider"

Then run the migrations to create the personal_access_tokens table:

php artisan migrate

For SPA authentication, you additionally need to add the EnsureFrontendRequestsAreStateful middleware to the HTTP kernel (file app/Http/Kernel.php):

'api' => [\n    \\Laravel\\Sanctum\\Http\\Middleware\\EnsureFrontendRequestsAreStateful::class,\n    'throttle:api',\n    \\Illuminate\\Routing\\Middleware\\SubstituteBindings::class,\n],

Also, in the .env file, specify your SPA domain:

SANCTUM_STATEFUL_DOMAINS=localhost:8080

3. Quick Start — Minimal Working Example

Let's look at a minimal example of issuing an API token and protecting a route.

Step 1: User Model

In the App\\Models\\User model, use the HasApiTokens trait:

validate([\n        'email' => 'required|email',\n        'password' => 'required',\n    ]);\n\n    if (auth()->attempt($credentials)) {\n        $user = auth()->user();\n        $token = $user->createToken('api-token')->plainTextToken;\n        \n        ret