Autenticación Laravel Sanctum: Guía API y SPA (2025)

• 02/09/2025

Dominando Laravel Sanctum: Guía Paso a Paso para Autenticación API y SPA

En el amplio universo del desarrollo web moderno, la autenticación de usuarios es una piedra angular que garantiza la seguridad y la privacidad de las aplicaciones. Cuando construyes APIs robustas o Single Page Applications (SPAs), necesitas una solución de autenticación eficiente y sencilla de implementar. Aquí es donde Laravel Sanctum se presenta como tu aliado ideal.

Este tutorial de Laravel Sanctum te guiará paso a paso para que domines esta herramienta, la solución ligera y efectiva de Laravel para la autenticación de APIs y autenticación SPA Laravel. Desde su instalación inicial hasta la protección de rutas API Laravel, aprenderás todo lo necesario para implementar Sanctum en tus proyectos. Prepárate para proteger API Laravel de forma sencilla y potente, y a crear API con Laravel Sanctum de manera segura.

Únete a nuestra comunidad de Discord

¿Qué es Laravel Sanctum? Autenticación Ligera para APIs y SPAs

Laravel Sanctum es un paquete de autenticación que simplifica la protección de APIs para aplicaciones de una sola página (SPAs), aplicaciones móviles y clientes de terceros basados en tokens. A diferencia de soluciones más complejas como Laravel Passport (enfocado en OAuth2), Sanctum se centra en la autenticación basada en tokens de forma eficiente y sin sobrecarga.

Su principal ventaja reside en su flexibilidad. Puede gestionar la autenticación SPA Laravel utilizando cookies y sesiones (aprovechando la protección CSRF de Laravel) y, al mismo tiempo, permite la emisión de Sanctum token personalizados para otros clientes. Esto lo convierte en una opción ideal para la mayoría de los proyectos modernos que requieren una autenticación API REST Laravel sin la complejidad de OAuth2.

Sanctum ofrece una alternativa más sencilla a JWT Laravel Sanctum en muchos escenarios, especialmente cuando trabajas dentro del ecosistema de Laravel. Además, se integra perfectamente con el sistema de autenticación existente de Laravel, lo que facilita enormemente su adopción. Aprender cómo usar Laravel Sanctum te ahorrará mucho tiempo y quebraderos de cabeza, convirtiéndote en un experto en autenticación Laravel 12.

---

Instalación y Configuración Básica de Laravel Sanctum

La instalación de Laravel Sanctum es un proceso directo que se realiza con unos pocos comandos. Sigue estos pasos para integrar Sanctum en tu proyecto y realizar su configuración inicial, preparándote para la autenticación API REST Laravel.

1. Instalar Laravel Sanctum vía Composer: Abre tu terminal en la raíz de tu proyecto Laravel y ejecuta el siguiente comando:

   composer require laravel/sanctum

   Este comando descargará el paquete y lo añadirá a las dependencias de tu proyecto.

2. Publicar los archivos de configuración y migración: Una vez instalado, debes publicar los archivos de configuración y las migraciones de Sanctum. Esto creará el archivo config/sanctum.php y una migración para la tabla personal_access_tokens.

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

   Si se te pregunta qué proveedor publicar, selecciona Laravel\Sanctum\SanctumServiceProvider.

3. Ejecutar las migraciones de la base de datos: Ahora que tienes la migración de Sanctum, debes ejecutarla para crear la tabla personal_access_tokens en tu base de datos. Esta tabla es crucial para almacenar los Sanctum token de acceso personal.

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

   Tras ejecutar este comando, verás la tabla personal_access_tokens en tu base de datos, lista para ser utilizada por Sanctum.

4. Añadir el trait HasApiTokens a tu modelo User: Para que tu modelo de usuario pueda generar y gestionar Sanctum token, debes añadir el trait HasApiTokens proporcionado por Sanctum. Abre el archivo app/Models/User.php y modifícalo de la siguiente manera:

   <?php
   
   namespace App\Models;
   
   use Illuminate\Contracts\Auth\MustVerifyEmail;
   use Illuminate\Database\Eloquent\Factories\HasFactory;
   use Illuminate\Foundation\Auth\User as Authenticatable;
   use Illuminate\Notifications\Notifiable;
   use Laravel\Sanctum\HasApiTokens; // Asegúrate de importar esto
   
   class User extends Authenticatable
   {
       use HasApiTokens, HasFactory, Notifiable; // Añade HasApiTokens aquí
   
       protected $fillable = [
           'name',
           'email',
           'password',
       ];
   
       protected $hidden = [
           'password',
           'remember_token',
       ];
   
       protected $casts = [
           'email_verified_at' => 'datetime',
           'password' => 'hashed',
       ];
   }
   

   Este trait añade métodos importantes como createToken y tokens a tu modelo de usuario, permitiéndole interactuar con los Sanctum token.

5. Configurar los dominios SPA para autenticación basada en cookies: Si vas a utilizar Laravel Sanctum para autenticar una SPA que reside en un dominio diferente al de tu API (por ejemplo, mi-frontend.com y api.mi-backend.com), debes configurar los dominios permitidos en config/sanctum.php. Abre config/sanctum.php y busca la clave stateful_domains. Añade los dominios de tu frontend.

   // config/sanctum.php
   
   'stateful_domains' => [
   'localhost',
   'localhost:3000', // Ejemplo si tu frontend corre en este puerto
   'mi-frontend.com', // El dominio de tu aplicación SPA
   // Añade más dominios si es necesario, sin el protocolo (http:// o https://)
   ],

   Es crucial que incluyas el dominio (y puerto si no es el predeterminado) de tu frontend aquí. No incluyas el esquema (http:// o https://) en estos dominios. Laravel utiliza el APP_URL de tu .env para la url de la API, y SESSION_DOMAIN si necesitas compartir la sesión entre subdominios.

6. Configurar CORS para tu SPA (si es necesario): Si tu SPA está en un dominio diferente, necesitarás configurar CORS (Cross-Origin Resource Sharing) para permitir que el frontend se comunique con tu backend. Abre config/cors.php y ajusta las opciones:

   // config/cors.php
   
   'paths' => ['api/*', 'sanctum/csrf-cookie'], // Asegúrate de que sanctum/csrf-cookie esté aquí
   'allowed_origins' => ['http://localhost:3000', 'https://mi-frontend.com'], // O el dominio específico de tu frontend. ¡No usar '*' en producción!
   'allowed_methods' => ['*'],
   'allowed_headers' => ['*'],
   'supports_credentials' => true, // ¡Esto es clave para la autenticación basada en cookies con SPAs!

   Para entornos de producción, se recomienda especificar los dominios exactos en allowed_origins en lugar de * por razones de seguridad. supports_credentials es vital para que las cookies sean enviadas y recibidas en solicitudes de origen cruzado, lo cual es fundamental para la autenticación SPA Laravel con cookies de sesión.

Con estos pasos, Laravel Sanctum estará completamente instalado y configurado en tu aplicación, listo para proteger API Laravel y gestionar la autenticación de manera efectiva.

---

Protegiendo Rutas API con Laravel Sanctum: Tu Primer Token

Ahora que Sanctum está instalado, es hora de ponerlo a trabajar protegiendo rutas API Laravel. Este proceso implica crear un endpoint para la autenticación, definir rutas que requieran autenticación y generar un Sanctum token para acceder a ellas. Este es un Laravel Sanctum ejemplo práctico de cómo funciona.

Creación de la API y Modelos Necesarios

Para este ejemplo, asumiremos que tienes un modelo User existente (el que modificamos antes con HasApiTokens). Vamos a crear una ruta simple a la que solo los usuarios autenticados puedan acceder.

Primero, asegúrate de que tu modelo User en app/Models/User.php siga teniendo el trait HasApiTokens:

// app/Models/User.php
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;

    // ...
}

Luego, vamos a crear un controlador básico para gestionar el login y la generación de tokens.

php artisan make:controller Auth/AuthController

Dentro de app/Http/Controllers/Auth/AuthController.php, puedes añadir un método login para autenticar usuarios y generar tokens, así como logout y user:

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Hash;
use App\Models\User; // Asegúrate de importar el modelo User

class AuthController extends Controller
{
    /**
     * Maneja el login de usuario y genera un token de acceso personal.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function login(Request $request)
    {
        $request->validate([
            'email' => 'required|email',
            'password' => 'required',
            'device_name' => 'required|string', // Para identificar el token
        ]);

        $user = User::where('email', $request->email)->first();

        if (! $user || ! Hash::check($request->password, $user->password)) {
            return response()->json(['message' => 'Credenciales inválidas'], 401);
        }

        // Eliminar tokens antiguos del dispositivo específico si deseas
        // $user->tokens()->where('name', $request->device_name)->delete();

        // Generar un nuevo token de acceso personal (plainTextToken para API REST)
        $token = $user->createToken($request->device_name)->plainTextToken;

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

    /**
     * Cierra la sesión del usuario revocando el token actual.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function logout(Request $request)
    {
        // Revocar el token actual del usuario autenticado
        $request->user()->currentAccessToken()->delete();

        return response()->json(['message' => 'Sesión cerrada correctamente.']);
    }

    /**
     * Devuelve los datos del usuario autenticado.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function user(Request $request)
    {
        // Devolver los datos del usuario autenticado por Sanctum
        return response()->json($request->user());
    }
}

Este controlador proporciona funciones básicas para iniciar sesión, cerrar sesión y obtener los datos del usuario autenticado, fundamental para cualquier API Laravel Sanctum.

Configuración de las Guards en config/auth.php

Laravel Sanctum funciona con el sistema de guards de autenticación de Laravel. Aunque Sanctum se registra automáticamente, es útil entender cómo está configurado. Abre config/auth.php y verás una sección guards y providers.

// config/auth.php

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'sanctum' => [
        'driver' => 'sanctum',
        'provider' => 'users',
    ],
],

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\Models\User::class,
    ],
],

Aquí puedes ver que sanctum tiene su propio driver y utiliza el provider de users (tu modelo User). Esto significa que puedes usar auth:sanctum como middleware para proteger API Laravel con tus rutas.

Definición de Rutas Protegidas en routes/api.php

Ahora, vamos a definir las rutas en tu archivo routes/api.php. Incluiremos las rutas de login y logout, y una ruta protegida para demostrar la autenticación API REST Laravel.

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Auth\AuthController; // Importa tu controlador AuthController

// Rutas de autenticación (no protegidas por Sanctum directamente, sino para generar tokens/sesiones)
Route::post('/login', [AuthController::class, 'login']);

// Grupo de rutas protegidas por el middleware de Sanctum
Route::middleware('auth:sanctum')->group(function () {
    Route::post('/logout', [AuthController::class, 'logout']);
    Route::get('/user', [AuthController::class, 'user']); // Ruta para obtener información del usuario

    // Añade aquí más rutas que necesiten autenticación
    Route::get('/items', function (Request $request) {
        return response()->json(['message' => 'Acceso a items permitido para ' . $request->user()->name, 'user_id' => $request->user()->id]);
    });
});

Con Route::middleware('auth:sanctum'), cualquier solicitud a las rutas dentro de ese grupo será interceptada por el middleware de Sanctum. Si la solicitud no contiene un Sanctum token válido o una sesión activa (en el caso de SPA), Laravel devolverá un error 401 Unauthorized, protegiendo tu API Laravel de accesos no autorizados.

Para probar esto, puedes hacer una solicitud POST a /api/login con email, password y device_name (ej. Postman Desktop). Recibirás un plainTextToken. Luego, usa ese token en el encabezado Authorization: Bearer <tu_token> para acceder a /api/user o /api/items.

---

Autenticación SPA con Laravel Sanctum: Un Ejemplo Práctico

La autenticación SPA con Laravel Sanctum es una de sus características más potentes y, a menudo, la que genera más confusión. A diferencia de las APIs tradicionales que usan tokens de portador persistentes en el frontend, Sanctum para SPAs aprovecha las cookies de sesión y la protección CSRF de Laravel.

El flujo básico para una SPA que reside en un dominio diferente es el siguiente:

1. La SPA realiza una solicitud GET a /sanctum/csrf-cookie para obtener una cookie XSRF-TOKEN. Esta cookie es enviada por el navegador en cada solicitud subsiguiente.

2. La SPA envía credenciales de usuario (email, contraseña) a tu endpoint de login de Laravel (ej. /api/login).

3. Laravel autentica al usuario y crea una sesión. La cookie de sesión (laravel_session) se envía de vuelta al navegador del frontend.

4. Para las solicitudes posteriores, el navegador enviará automáticamente la cookie de sesión y la cookie XSRF-TOKEN (que debe ser enviada por JavaScript como encabezado X-XSRF-TOKEN o X-CSRF-TOKEN) con cada solicitud autenticada a tu backend.

Implementación del Login en el Frontend (con axios)

Para el frontend, usaremos JavaScript (con axios como cliente HTTP) para ilustrar el proceso. Este código iría en tu SPA (React, Vue, Angular, etc.).

import axios from 'axios';

// 1. Configurar axios globalmente para tu API
// Asegúrate de que tu URL base de la API esté configurada correctamente
axios.defaults.baseURL = 'http://localhost:8000/api'; // Cambia a la URL base de tu backend (sin /api)
// Y para permitir el envío y recepción de cookies y credenciales
axios.defaults.withCredentials = true;

async function loginUser(email, password) {
    try {
        console.log('Iniciando sesión para:', email);

        // 1. Obtener la cookie CSRF de Laravel Sanctum
        // Esta ruta (sanctum/csrf-cookie) debe ser accesible desde tu frontend
        await axios.get('http://localhost:8000/sanctum/csrf-cookie');
        console.log('Cookie CSRF obtenida correctamente.');

        // 2. Enviar las credenciales de login
        // La ruta de login es la que definimos en routes/api.php
        const response = await axios.post('/login', {
            email: email,
            password: password,
            device_name: 'spa-browser-client' // Un nombre para identificar el token de sesión
        });

        // Ojo: Para SPA con Sanctum, no se devuelve un token "Bearer" para cada request.
        // Se establece una sesión basada en cookies. El 'token' en la respuesta de login
        // sería el personal access token si lo generaras para un uso diferente (ej. API Key).
        // Para SPA, la sesión se mantiene por la cookie gestionada por el navegador.
        console.log('¡Login exitoso!', response.data);

        // Si el login fue exitoso, puedes redirigir al usuario o cargar contenido protegido
        // Por ejemplo, solicitar datos del usuario autenticado
        const userResponse = await axios.get('/user');
        console.log('Datos del usuario autenticado:', userResponse.data);

    } catch (error) {
        console.error('Fallo el login:', error.response ? error.response.data : error.message);
        // Mostrar mensaje de error al usuario
    }
}

// Ejemplo de uso: (asegúrate de que existe un usuario con estas credenciales en tu DB)
// loginUser('[email protected]', 'password');

// Función para cerrar sesión
async function logoutUser() {
    try {
        await axios.post('/logout');
        console.log('Sesión cerrada correctamente.');
        // Redirigir al usuario a la página de login o inicio
    } catch (error) {
        console.error('Error al cerrar sesión:', error.response ? error.response.data : error.message);
    }
}

// Función para obtener datos protegidos después del login
async function fetchProtectedData() {
    try {
        const response = await axios.get('/items');
        console.log('Datos protegidos:', response.data);
    } catch (error) {
        console.error('Fallo al obtener datos protegidos:', error.response ? error.response.data : error.message);
    }
}

// Para probar:
// loginUser('[email protected]', 'tu_password').then(() => {
//     fetchProtectedData();
//     // logoutUser(); // Para probar el cierre de sesión
// });

Es vital que axios.defaults.withCredentials = true; esté configurado. Esto permite que el navegador envíe y reciba cookies de tu backend, lo cual es fundamental para la autenticación basada en sesión de Sanctum para SPAs.

Almacenamiento y Envío del Token Sanctum en SPAs

Para autenticación SPA Laravel, el "token" al que nos referimos es la sesión de Laravel mantenida a través de cookies. Laravel Sanctum asegura que, después de la primera solicitud a /sanctum/csrf-cookie y un inicio de sesión exitoso, el navegador guarde automáticamente las cookies necesarias (laravel_session y XSRF-TOKEN).

El navegador se encarga de enviar estas cookies en cada solicitud posterior al mismo dominio (o a los stateful_domains configurados en config/sanctum.php). Tu JavaScript no necesita almacenar explícitamente un token de portador en el localStorage o sessionStorage para la autenticación de SPAs.

Cuando hagas solicitudes POST, PUT, PATCH o DELETE, Axios se encargará automáticamente de leer la cookie XSRF-TOKEN y enviarla como encabezado X-XSRF-TOKEN (o X-CSRF-TOKEN). Esto es crucial para la protección CSRF que Laravel proporciona.

La simplicidad de Sanctum para SPAs radica en delegar la gestión del estado de la autenticación al navegador y a las características de seguridad incorporadas de Laravel.

Manejo de Errores de Autenticación en SPAs

El manejo de errores es una parte crucial de cualquier sistema de autenticación. Para la autenticación SPA con Sanctum, los errores más comunes suelen ser respuestas 401 (Unauthorized) o 419 (CSRF Token Mismatch).

Cuando una solicitud protegida por auth:sanctum falla la autenticación (por ejemplo, la sesión ha caducado, la cookie no se envía o hay un problema de CSRF), Laravel devolverá una respuesta HTTP con un código de estado de error.

• - 401 Unauthorized: Indica que la solicitud no fue autenticada. Esto puede ocurrir si la sesión ha expirado, si las cookies no se están enviando correctamente (revisa withCredentials) o si el usuario no ha iniciado sesión.

• - 419 Page Expired (CSRF Token Mismatch): Esto ocurre si el token CSRF esperado no está presente o no coincide. Asegúrate de hacer la solicitud GET /sanctum/csrf-cookie antes de cualquier solicitud POST/PUT/PATCH/DELETE y de que tus dominios estén correctamente configurados en config/sanctum.php y config/cors.php.

Tu frontend debería tener una lógica para interceptar estos errores, por ejemplo, redirigiendo al usuario a la página de login o mostrando un mensaje de error apropiado.

// Configura un interceptor de respuesta global en axios
axios.interceptors.response.use(
    response => response,
    error => {
        if (error.response) {
            if (error.response.status === 401) {
                console.error('Error de autenticación: Sesión expirada o no iniciada.');
                // Redirigir al usuario a la página de login
                // window.location.href = '/login';
            } else if (error.response.status === 419) {
                console.error('Error CSRF: La página ha expirado o token no coincide.');
                // Recargar la página o solicitar nueva cookie CSRF y volver a intentar login
                // window.location.reload();
            }
        }
        return Promise.reject(error);
    }
);

Un buen manejo de errores mejora significativamente la experiencia del usuario y la robustez de tu aplicación al usar Laravel Sanctum para principiantes.

---

Autenticación API REST con Sanctum: Generando Tokens de Acceso Personal

Mientras que la autenticación SPA Laravel se basa en cookies de sesión, para aplicaciones móviles, aplicaciones de escritorio o clientes de terceros, Laravel Sanctum permite la generación de "tokens de acceso personal" (Personal Access Tokens - PATs). Estos tokens son similares a las claves API y se utilizan como tokens de portador (Bearer tokens) en el encabezado Authorization. Esta es la forma más común de autenticación API REST Laravel.

Para generar un token de acceso personal, un usuario debe haber iniciado sesión de alguna manera, o debes tener un mecanismo para emitir tokens a través de un panel de administración, por ejemplo. En nuestro AuthController que creamos previamente, el método login ya genera un token de esta manera:

// Dentro de AuthController@login
$token = $user->createToken($request->device_name)->plainTextToken;
return response()->json(['token' => $token, 'user' => $user]);

El método createToken($name, $abilities) del trait HasApiTokens genera un nuevo Sanctum token para el usuario.

• - $name: Es un nombre descriptivo para el token (ej. "iPhone de Juan", "API Key de mi-app"). Esto ayuda a identificar el token en la base de datos y a revocarlo si es necesario.

• - $abilities (opcional): Es un array de cadenas que definen las "habilidades" o permisos que tiene este token. Esto se usa con el sistema de autorización de Laravel (Gates y Policies) para un control de acceso más granular.

El método plainTextToken devuelve la cadena del token que debes proporcionar a tu cliente API. Es crucial que este Sanctum token se maneje con seguridad, ya que otorga acceso a tu API.

Uso de Tokens para Consumir la API

Una vez que tu cliente API (aplicación móvil, Postman, cURL, etc.) ha recibido el plainTextToken, debe incluirlo en el encabezado Authorization de cada solicitud a las rutas protegidas.

El formato del encabezado es: Authorization: Bearer <TU_TOKEN_GENERADO>.

Ejemplo de solicitud con cURL:

curl -X GET \
  http://localhost:8000/api/user \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer AQUI_VA_TU_TOKEN'

Ejemplo de solicitud con JavaScript (fetch API, para clientes no SPA):

async function fetchProtectedDataWithToken(token) {
    try {
        const response = await fetch('http://localhost:8000/api/items', {
            method: 'GET',
            headers: {
                'Accept': 'application/json',
                'Authorization': `Bearer ${token}`
            }
        });

        if (!response.ok) {
            const errorData = await response.json();
            throw new Error(errorData.message || 'Error al obtener datos protegidos.');
        }

        const data = await response.json();
        console.log('Datos protegidos con token:', data);
    } catch (error) {
        console.error('Error al solicitar datos protegidos:', error);
    }
}

// Usa el token obtenido del endpoint de login (después de una solicitud POST a /api/login)
// fetchProtectedDataWithToken('el_token_que_recibiste');

Los tokens de acceso personal son la forma más segura y flexible de autenticar clientes que no son SPAs, ya que no dependen de las sesiones de navegador y cookies, y son ideales para crear API con Laravel Sanctum para apps móviles.

Puedes gestionar los Sanctum token de un usuario a través de la relación tokens() del trait HasApiTokens:

// Obtener todos los tokens de un usuario
$user->tokens; // Devuelve una colección de tokens

// Revocar un token específico (por ID)
$user->tokens()->where('id', $tokenId)->delete();

// Revocar todos los tokens de un usuario
$user->tokens()->delete();

// Revocar el token actual usado en la petición (útil para el logout de clientes API)
$request->user()->currentAccessToken()->delete();

Esto te proporciona un control total sobre los Sanctum token emitidos, lo que es fundamental para la seguridad y la gestión de sesiones.

---

Conclusión: Dominando la Autenticación API con Laravel Sanctum

Hemos recorrido un camino completo en este tutorial Laravel Sanctum, desde la instalación y configuración básica hasta la protección de rutas API Laravel y la implementación de la autenticación tanto para SPAs como para APIs RESTful. Has aprendido a gestionar Sanctum token de acceso personal y a manejar los errores más comunes, además de incorporar buenas prácticas de seguridad y escalabilidad.

Laravel Sanctum demuestra ser una solución de autenticación excepcionalmente versátil y eficiente para el ecosistema de Laravel. Su ligereza y facilidad de integración lo convierten en una opción preferente para la mayoría de las necesidades de autenticación de APIs modernas, permitiéndote concentrarte en la lógica de negocio de tu aplicación. Dominar esta herramienta te equipa con una habilidad fundamental para el desarrollo de aplicaciones web seguras y escalables. ¡Ahora estás listo para implementar Sanctum en tus proyectos y llevar la seguridad de tus APIs al siguiente nivel!