Tema 15 · Laravel Sanctum

15. Autenticación de APIs con Laravel Sanctum: Emisión de Tokens Bearer y Rutas Protegidas

Implementa autenticación segura para Single Page Applications (SPAs) y aplicaciones móviles mediante Bearer Tokens con revocación granular.

¿Por qué Usar Laravel Sanctum para APIs?

En aplicaciones web tradicionales, la autenticación se maneja mediante cookies de sesión guardadas en el navegador. Sin embargo, en aplicaciones móviles (Flutter, React Native) o servicios de terceros, las cookies no son prácticas o no existen.

Laravel Sanctum es el paquete oficial y ligero que resuelve este problema mediante la emisión de API Tokens (Bearer Tokens) criptográficamente seguros.

# En Laravel moderno Sanctum viene preinstalado, o se activa con:
php artisan install:api

El Trait HasApiTokens en el Modelo User

Para habilitar la generación de tokens en tu modelo User, simplemente incluyes el trait HasApiTokens:

namespace App\Models;

use Laravel\Sanctum\HasApiTokens;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasApiTokens; // Habilita createToken(), tokens(), etc.
}

El Flujo de Autenticación con Tokens

  1. Login: El cliente envía correo y contraseña vía POST /api/login.
  2. Validación: Si las credenciales son correctas, el servidor genera un token con $user->createToken('dispositivo')->plainTextToken y lo devuelve en el JSON.
  3. Peticiones Subsiguientes: En cada petición a una ruta protegida, el cliente incluye el token en el encabezado HTTP:
    Authorization: Bearer 1|Xk8L0...tokenSecreto...
  4. Rutas Protegidas: En routes/api.php se protegen con el middleware auth:sanctum:
    Route::middleware('auth:sanctum')->get('/usuario/perfil', function (Request $request) {
        return $request->user();
    });
  5. Logout (Revocación): Para cerrar sesión, se revoca el token actual: $request->user()->currentAccessToken()->delete();.

⚡ Controlador de Autenticación de API con Emisión y Revocación de Tokens

Endpoints de inicio de sesión (/api/login) y cierre de sesión (/api/logout) con Sanctum.

ApiAuthController.php
Solo lectura
<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

class ApiAuthController extends Controller
{
    /** Genera un token Bearer tras verificar credenciales */
    public function login(Request $request): JsonResponse
    {
        $request->validate([
            'email'       => 'required|email',
            'password'    => 'required|string',
            'device_name' => 'required|string', // ej: "iPhone 15", "App Android"
        ]);

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

        // Verificar que el usuario exista y que la clave coincida con el hash
        if (!$user || !Hash::check($request->password, $user->password)) {
            throw ValidationException::withMessages([
                'email' => ['Las credenciales proporcionadas son incorrectas.'],
            ]);
        }

        // Crear el token con Sanctum
        $token = $user->createToken($request->device_name)->plainTextToken;

        return response()->json([
            'status' => 'success',
            'token'  => $token,
            'user'   => [
                'id'    => $user->id,
                'name'  => $user->name,
                'email' => $user->email,
            ],
        ], 200);
    }

    /** Revoca el token actual (Logout) */
    public function logout(Request $request): JsonResponse
    {
        // Elimina únicamente el token del dispositivo que hizo logout
        $request->user()->currentAccessToken()->delete();

        return response()->json([
            'status'  => 'success',
            'message' => 'Sesión cerrada y token revocado correctamente.',
        ], 200);
    }
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Cuál es el nombre del middleware que protege rutas API verificando el Bearer Token emitido por Laravel Sanctum?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar Laravel Framework Profesional y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.