Laravel Sanctum para PHP: guía completa de API tokens y autenticación SPA

1. ¿Qué es y para qué sirve?

Laravel Sanctum es una biblioteca ligera de autenticación para el framework PHP Laravel, diseñada para gestionar tokens de API y aplicaciones de una sola página (SPA). Desarrollada por Taylor Otwell y el equipo de Laravel, Sanctum ofrece una forma simple pero potente de proteger rutas de API, permitiendo a los desarrolladores implementar autenticación rápidamente sin la compleja configuración que requieren soluciones más pesadas como Passport (OAuth2).

El objetivo principal de Sanctum es resolver dos problemas clave del desarrollo web moderno: la autenticación para SPA (Single Page Applications) que operan en el mismo dominio que el backend, y la emisión de tokens API para aplicaciones móviles o servicios de terceros. A diferencia de Passport, Sanctum no utiliza el protocolo OAuth2 completo, lo que lo convierte en la opción ideal para proyectos que no necesitan un sistema complejo de delegación de accesos. Utiliza sesiones de Laravel para la autenticación SPA y tokens simples basados en HMAC para la API.

La biblioteca viene incluida de serie en Laravel 8 y versiones superiores, lo que la hace disponible "listo para usar". Sanctum es especialmente útil para startups, equipos pequeños y proyectos donde la velocidad de desarrollo y el mínimo de dependencias son importantes. Gestiona automáticamente la caducidad de los tokens, soporta "habilidades" (abilities) para un control detallado de permisos y se integra fácilmente con Laravel Fortify, Breeze o Jetstream.

2. Instalación

Laravel Sanctum se instala a través de Composer, el gestor de paquetes estándar para PHP. Asegúrate de tener instalado PHP 8.0 o superior y Laravel 8.x/9.x/10.x/11.x.

El comando exacto para la instalación es:

composer require laravel/sanctum

Después de la instalación, debes publicar el archivo de configuración y las migraciones de la base de datos:

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

Luego, ejecuta las migraciones para crear la tabla personal_access_tokens:

php artisan migrate

Para la autenticación SPA, adicionalmente debes agregar el middleware EnsureFrontendRequestsAreStateful en el kernel HTTP (archivo app/Http/Kernel.php):

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

También en el archivo .env especifica el dominio de tu SPA:

SANCTUM_STATEFUL_DOMAINS=localhost:8080

3. Inicio rápido — ejemplo mínimo funcional

Veamos un ejemplo mínimo de emisión de token API y protección de rutas.

Paso 1: Modelo User

En el modelo App\Models\User usa el trait HasApiTokens:

validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (auth()->attempt($credentials)) {
        $user = auth()->user();
        $token = $user->createToken('api-token')->plainTextToken;
        
        return response()->json([
            'token' => $token,
            'user' => $user
        ]);
    }