Laravel Sanctum (autenticación con API tokens)

Aprende a implementar la autenticación con API tokens y SPA con Laravel Sanctum. Desde la instalación del paquete hasta el uso avanzado, con un enfoque práctico.

​

Qué es Sanctum

Laravel Sanctum es un paquete de autenticación ligero pensado para SPAs (single page applications), apps móviles y APIs sencillas. Puedes emitir y gestionar varios API tokens por usuario sin necesidad de dominar OAuth.

Sanctum cubre dos casos de uso:

Modo de autenticación	Mecanismo	Uso típico
API tokens	Cabecera Authorization: Bearer <token>	Apps móviles, integraciones de terceros
SPA	Cookie de sesión + protección CSRF	Frontend propio (Vue/React, etc.)

Si tu SPA llama a la API que tú mismo controlas, usa el modo SPA. Si la API la consumen apps móviles o terceros, usa API tokens. Puedes usar uno solo o los dos.

​

Sanctum frente a Passport

	Sanctum	Passport
Complejidad	Sencillo	OAuth2 completo
Ideal para	SPA y apps móviles propias	Ser proveedor OAuth para terceros
Tipo de token	Personal access tokens	Access tokens OAuth2

Si necesitas actuar como proveedor OAuth2 hacia otros, elige Passport. Para la mayoría de aplicaciones, Sanctum es suficiente.

---

​

Instalación y configuración

​

Instalación

Con el comando Artisan install:api se instala Sanctum.

php artisan install:api

Este comando:

• Instala el paquete laravel/sanctum.
• Publica la migración de la tabla personal_access_tokens.
• Ejecuta la migración.

​

Añadir el trait HasApiTokens

Añade el trait HasApiTokens al modelo User.

// app/Models/User.php

use Laravel\Sanctum\HasApiTokens;

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

Con esto puedes usar métodos como $user->createToken() o $user->tokens.

---

​

Autenticación con API tokens

​

Flujo de tokens

​

Emitir un token

Usa createToken(). La propiedad plainTextToken contiene el valor en texto plano. Ese valor no se guarda en la base de datos, por lo que debes devolvérselo al usuario inmediatamente.

use Illuminate\Http\Request;

Route::post('/tokens/create', function (Request $request) {
    $token = $request->user()->createToken($request->token_name);

    return ['token' => $token->plainTextToken];
})->middleware('auth');

En la base de datos se guarda el token con hash SHA-256.

​

Configurar scopes (abilities)

Puedes asignar abilities (scopes) al token para restringir las operaciones que permite.

// Token con scopes
$token = $user->createToken('mobile-app', ['server:update', 'server:read']);

return $token->plainTextToken;

Al procesar la petición, comprueba los scopes.

if ($request->user()->tokenCan('server:update')) {
    // Ejecutar la operación de actualización
}

if ($request->user()->tokenCant('server:update')) {
    abort(403);
}

​

Comprobar scopes con middleware

Registra el alias del middleware en bootstrap/app.php.

use Laravel\Sanctum\Http\Middleware\CheckAbilities;
use Laravel\Sanctum\Http\Middleware\CheckForAnyAbility;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'abilities' => CheckAbilities::class,  // Todas las abilities
        'ability'   => CheckForAnyAbility::class, // Alguna ability
    ]);
})

Aplica el middleware a las rutas.

// Solo tokens con check-status y place-orders a la vez
Route::get('/orders', function () {
    // ...
})->middleware(['auth:sanctum', 'abilities:check-status,place-orders']);

// Tokens con check-status o place-orders
Route::get('/orders', function () {
    // ...
})->middleware(['auth:sanctum', 'ability:check-status,place-orders']);

​

Caducidad de los tokens

Por defecto los tokens de Sanctum no expiran. Configura la caducidad en minutos con expiration en config/sanctum.php.

// config/sanctum.php
'expiration' => 525600, // 365 días (en minutos)

También puedes indicar una caducidad por token.

$token = $user->createToken(
    'token-name',
    ['*'],
    now()->addWeeks(1) // Caduca en 1 semana
)->plainTextToken;

Con caducidad activada, conviene programar la limpieza de tokens expirados.

use Illuminate\Support\Facades\Schedule;

Schedule::command('sanctum:prune-expired --hours=24')->daily();

​

Revocar tokens

// Eliminar todos los tokens
$user->tokens()->delete();

// Eliminar el token de la petición actual
$request->user()->currentAccessToken()->delete();

// Eliminar un token concreto
$user->tokens()->where('id', $tokenId)->delete();

---

​

Autenticación SPA

La autenticación SPA usa cookies de sesión, así que no necesitas emitir ni gestionar tokens. Es ideal para tu propio frontend (Vue, React, Next.js…) que consume tu API.

Para usar la autenticación SPA, el SPA y la API deben compartir dominio de nivel superior (los subdominios pueden ser distintos). Además, las peticiones deben incluir Accept: application/json y las cabeceras Referer u Origin.

​

Habilitar el middleware de Sanctum

Activa statefulApi() en bootstrap/app.php.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->statefulApi();
})

​

Configurar los dominios first-party

Indica el dominio del SPA en la opción stateful de config/sanctum.php.

// config/sanctum.php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1',
    Sanctum::currentApplicationUrlWithPort()
))),

​

Configuración de CORS

Si tu API se consume desde otro subdominio, hay que configurar CORS.

php artisan config:publish cors

En config/cors.php pon supports_credentials a true.

// config/cors.php
'supports_credentials' => true,

También en axios del frontend.

// resources/js/bootstrap.js
axios.defaults.withCredentials = true;
axios.defaults.withXSRFToken = true;

No olvides configurar el dominio de la cookie de sesión.

// config/session.php
'domain' => '.example.com', // Con el punto inicial

​

Flujo de autenticación desde el SPA

1. Obtener la cookie CSRF

   Antes del login, llama a /sanctum/csrf-cookie para inicializar la protección CSRF.

   await axios.get('/sanctum/csrf-cookie');
   
2. Enviar la petición de login

   POST al endpoint /login.

   await axios.post('/login', {
       email: '[e-mail]',
       password: 'password',
   });
   
3. Enviar peticiones autenticadas

   Las peticiones posteriores se autentican automáticamente con la cookie.

   const response = await axios.get('/api/user');
   console.log(response.data); // Datos del usuario autenticado
   

---

​

Proteger rutas autenticadas

Aplica auth:sanctum a la ruta. Las peticiones no autenticadas reciben 401 Unauthorized. El mismo middleware sirve para API tokens y SPA.

use Illuminate\Http\Request;

// Ruta única
Route::get('/user', function (Request $request) {
    return $request->user();
})->middleware('auth:sanctum');

// Grupo de rutas
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/profile', [ProfileController::class, 'show']);
    Route::put('/profile', [ProfileController::class, 'update']);
    Route::get('/posts', [PostController::class, 'index']);
});

---

​

Ejemplo práctico: API de login que devuelve tokens

Ejemplo de autenticación con API tokens para una app móvil.

1. Crear el endpoint de login

   // routes/api.php
   
   use App\Models\User;
   use Illuminate\Http\Request;
   use Illuminate\Support\Facades\Hash;
   use Illuminate\Validation\ValidationException;
   
   Route::post('/sanctum/token', function (Request $request) {
       $request->validate([
           'email'       => ['required', 'email'],
           'password'    => ['required'],
           'device_name' => ['required', 'string'],
       ]);
   
       $user = User::where('email', $request->email)->first();
   
       if (! $user || ! Hash::check($request->password, $user->password)) {
           throw ValidationException::withMessages([
               'email' => ['Las credenciales proporcionadas no son válidas.'],
           ]);
       }
   
       return response()->json([
           'token' => $user->createToken($request->device_name)->plainTextToken,
       ]);
   });
   
2. Crear las rutas autenticadas

   // routes/api.php
   
   Route::middleware('auth:sanctum')->group(function () {
       // Devuelve el usuario actual
       Route::get('/user', function (Request $request) {
           return $request->user();
       });
   
       // Cierra sesión revocando el token actual
       Route::post('/logout', function (Request $request) {
           $request->user()->currentAccessToken()->delete();
   
           return response()->json(['message' => 'Sesión cerrada.']);
       });
   
       // Cierra sesión en todos los dispositivos
       Route::post('/logout/all', function (Request $request) {
           $request->user()->tokens()->delete();
   
           return response()->json(['message' => 'Sesión cerrada en todos los dispositivos.']);
       });
   });
   
3. Consumirlo desde el cliente

   // Login
   const { data } = await axios.post('/api/sanctum/token', {
       email: '[e-mail]',
       password: 'password',
       device_name: 'My iPhone',
   });
   
   const token = data.token;
   
   // Peticiones autenticadas
   const response = await axios.get('/api/user', {
       headers: {
           Authorization: `Bearer ${token}`,
       },
   });
   

---

​

Pruebas

En los tests de Sanctum utiliza Sanctum::actingAs() para autenticar a un usuario y asignar abilities.

Pest

use App\Models\User;
use Laravel\Sanctum\Sanctum;

test('se puede obtener el listado de tareas', function () {
    Sanctum::actingAs(
        User::factory()->create(),
        ['view-tasks']
    );

    $response = $this->get('/api/tasks');

    $response->assertOk();
});

test('un token con todas las abilities puede acceder', function () {
    Sanctum::actingAs(
        User::factory()->create(),
        ['*']
    );

    $response = $this->get('/api/tasks');

    $response->assertOk();
});

PHPUnit

use App\Models\User;
use Laravel\Sanctum\Sanctum;

public function test_task_list_can_be_retrieved(): void
{
    Sanctum::actingAs(
        User::factory()->create(),
        ['view-tasks']
    );

    $response = $this->get('/api/tasks');

    $response->assertOk();
}

---

​

Resumen

Instalación

# Instalar Sanctum y ejecutar migraciones
php artisan install:api

Añade HasApiTokens al modelo User:

use Laravel\Sanctum\HasApiTokens;

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

API habitual

// Emitir token
$token = $user->createToken('token-name')->plainTextToken;

// Emitir token con scopes
$token = $user->createToken('token-name', ['read', 'write'])->plainTextToken;

// Comprobar scope
$user->tokenCan('read');   // true/false
$user->tokenCant('write'); // true/false

// Revocar
$user->tokens()->delete();                        // Todos
$request->user()->currentAccessToken()->delete(); // El actual
$user->tokens()->where('id', $id)->delete();      // Uno concreto

Cuándo usar cada modo

• API tokens: apps móviles, terceros, CLI… clientes sin sesión.
• Autenticación SPA: tu propio frontend Vue/React/Next.js sobre el mismo dominio (o subdominio). Más seguro y sin gestión de tokens.