Laravel Sanctum: tokens API y autenticación para SPAs

Sanctum frente a JWT y Fortify

Laravel Sanctum es el paquete oficial para autenticación en APIs y SPAs (Single Page Applications). A diferencia de paquetes JWT externos, Sanctum viene integrado con Laravel y ofrece dos flujos:

1. Tokens API: para clientes móviles, servicios de terceros o frontends que no comparten dominio con el backend.
2. Autenticación por sesión: para SPAs que se sirven desde el mismo dominio que la API (cookie-based, sin tokens).

Sanctum no sustituye a Fortify (registro, login, reset de contraseña); ambos se complementan. Fortify gestiona las rutas y la lógica de autenticación; Sanctum gestiona la emisión de tokens y la protección de rutas API.

Sanctum es la opción recomendada para APIs REST en Laravel cuando no necesitas la flexibilidad de JWT ni integraciones con servicios externos que exijan ese formato.

Instalación y configuración

Sanctum se incluye en las instalaciones nuevas de Laravel. Si no lo tienes:

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

En proyectos recientes, el modelo User ya implementa HasApiTokens. Si no:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

En config/sanctum.php puedes ajustar la expiración de tokens y los dominios permitidos para autenticación por sesión (SPA).

Emisión de tokens API

Para que un cliente obtenga un token, expones un endpoint de login. El cliente envía email y password; el servidor valida y devuelve el token:

use Illuminate\Support\Facades\Auth;

Route::post('/login', function (Request $request) {
    $credentials = $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (!Auth::attempt($credentials)) {
        return response()->json(['message' => 'Credenciales inválidas'], 401);
    }

    $user = Auth::user();
    $token = $user->createToken('nombre-dispositivo')->plainTextToken;

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

El cliente debe enviar el token en la cabecera Authorization: Bearer {token} en cada petición protegida.

Protección de rutas API

Para exigir autenticación en rutas API, usa el middleware auth:sanctum:

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', function (Request $request) {
        return $request->user();
    });
    Route::apiResource('posts', PostController::class);
});

Las peticiones sin token válido reciben 401 Unauthorized.

Revocación de tokens

Un usuario puede revocar sus propios tokens:

$request->user()->currentAccessToken()->delete();

O todos los tokens del usuario:

$request->user()->tokens()->delete();

En un endpoint de logout típico:

Route::post('/logout', function (Request $request) {
    $request->user()->currentAccessToken()->delete();
    return response()->json(['message' => 'Sesión cerrada'], 200);
})->middleware('auth:sanctum');

Autenticación por sesión para SPAs

Cuando el frontend y el backend comparten dominio (por ejemplo, app.ejemplo.com y api.ejemplo.com con cookies configuradas), Sanctum puede usar cookies de sesión en lugar de tokens. Configura en config/sanctum.php el array stateful con los dominios permitidos y aplica el middleware EnsureFrontendRequestsAreStateful en bootstrap/app.php o en el kernel de API. Las peticiones desde el SPA enviarán la cookie de sesión automáticamente; no necesitas Bearer tokens en ese flujo.