Laravel Sanctum para PHP: guia completo de autenticação com API tokens e SPA

1. O que é e para que serve

Laravel Sanctum é uma biblioteca leve de autenticação para o framework PHP Laravel, projetada para gerenciar tokens de API e aplicações de página única (SPA). Desenvolvida por Taylor Otwell e pela equipe do Laravel, o Sanctum oferece uma maneira simples, porém poderosa, de proteger rotas de API, permitindo que desenvolvedores implementem autenticação rapidamente, sem a complexidade de soluções mais pesadas como o Passport (OAuth2).

O principal objetivo do Sanctum é resolver dois problemas cruciais do desenvolvimento web moderno: autenticação para SPAs (Single Page Applications) que rodam no mesmo domínio do backend, e emissão de tokens de API para aplicativos móveis ou serviços de terceiros. Diferente do Passport, o Sanctum não utiliza o protocolo OAuth2 completo, sendo a escolha ideal para projetos que não exigem um sistema complexo de delegação de acesso. Ele usa sessões do Laravel para autenticação SPA e tokens simples baseados em HMAC para APIs.

A biblioteca vem incluída por padrão no Laravel 8 e versões superiores, tornando-a disponível "pronta para uso". O Sanctum é especialmente útil para startups, equipes pequenas e projetos onde a velocidade de desenvolvimento e o mínimo de dependências são prioridades. Ele gerencia automaticamente a expiração de tokens, suporta "abilities" (habilidades) para controle de acesso refinado e se integra facilmente com Laravel Fortify, Breeze ou Jetstream.

2. Instalação

O Laravel Sanctum é instalado via Composer, o gerenciador de pacotes padrão para PHP. Certifique-se de ter PHP 8.0 ou superior e Laravel 8.x/9.x/10.x/11.x instalados.

Comando exato para instalação:

composer require laravel/sanctum

Após a instalação, é necessário publicar o arquivo de configuração e as migrações do banco de dados:

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

Em seguida, execute as migrações para criar a tabela personal_access_tokens:

php artisan migrate

Para autenticação SPA, é preciso adicionar o middleware EnsureFrontendRequestsAreStateful ao kernel HTTP (arquivo app/Http/Kernel.php):

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

Também no arquivo .env, defina o domínio do seu SPA:

SANCTUM_STATEFUL_DOMAINS=localhost:8080

3. Início rápido — exemplo funcional mínimo

Vamos ver um exemplo mínimo de emissão de token de API e proteção de rota.

Passo 1: Model User

No modelo App\Models\User, use a 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
        ]);
    }