APIs e Laravel Sanctum

Introdução

Ao desenvolver APIs com Laravel, um dos pontos mais importantes é garantir que apenas usuários autorizados consigam acessar determinados endpoints. Para isso, o Laravel oferece o Laravel Sanctum, uma solução simples, moderna e oficial para autenticação de APIs e aplicações SPA.

O Sanctum foi criado para resolver dois cenários muito comuns:

• Autenticação de APIs via tokens

• Autenticação de SPAs (Single Page Applications) usando cookies e sessão

Diferente de soluções mais complexas como OAuth2 (Laravel Passport), o Sanctum foca em simplicidade, segurança e produtividade, sendo ideal para a maioria dos projetos.

Neste tutorial, você vai entender como o Sanctum funciona, as diferenças entre os tipos de autenticação e como instalá-lo corretamente em um projeto Laravel.

Como funciona o Laravel Sanctum

O Laravel Sanctum funciona oferecendo uma camada de autenticação baseada em dois conceitos principais:

🔐 Tokens pessoais (Personal Access Tokens)

• Cada usuário pode ter um ou vários tokens

• Cada token é armazenado no banco de dados

• O cliente envia o token no header Authorization: Bearer

Internamente:

• O token é gerado uma única vez (plain text)

• Apenas o hash do token é salvo no banco

• O Laravel valida automaticamente o token a cada requisição

🍪 Autenticação baseada em cookies (SPA)

• Usa sessões do Laravel

• Proteção automática contra CSRF

• Ideal para aplicações frontend (React, Vue, etc.)

Nesse modo:

• O frontend solicita um cookie CSRF

• O login cria uma sessão autenticada

• As requisições seguintes usam cookies HttpOnly

O grande diferencial do Sanctum é permitir esses dois fluxos no mesmo projeto, sem conflito.

Diferença entre Tokens de API e Autenticação SPA

Essa é uma das partes mais importantes de entender antes de usar o Sanctum.

🔹 Tokens de API

Indicado para:

• Aplicativos mobile

• Integrações de terceiros

• APIs públicas ou privadas

• Sistemas externos

Características:

• Stateless (sem sessão)

• Token enviado no header

• Fácil de testar com Postman / Insomnia

• Pode ter permissões (abilities)

Exemplo de header:

Authorization: Bearer 1|xYzAbC123...

🔹 Autenticação SPA (Cookies)

Indicado para:

• React, Vue, Angular

• Frontend no mesmo domínio ou subdomínio

• Aplicações web modernas

Características:

• Usa sessão do Laravel

• Cookies HttpOnly

• Proteção CSRF

• Mais seguro contra XSS

Fluxo resumido:

1. /sanctum/csrf-cookie

2. /login

3. Requisições autenticadas automaticamente

🧠 Comparação rápida

As versões mais recentes do Laravel já incluem o Laravel Sanctum. No entanto, se o arquivo composer.json da sua aplicação não incluir o pacote laravel/sanctum, você pode seguir as instruções de instalação abaixo.

Instalação – Passo a passo

⚠️ Observação: Neste projeto, o Sanctum já está presente no composer.json, então não é necessário rodar composer require laravel/sanctum.

Passo 1 – Verificar dependência no composer.json:

"laravel/sanctum": "^3.3"

Se estiver presente, o pacote já está instalado.

Passo 2 – Publicar configurações

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

Isso cria:

• config/sanctum.php

• migrations necessárias

Passo 3 – Rodar as migrations

php artisan migrate

Será criada a tabela:

• personal_access_tokens

Passo 4 – Configurar o Model User

No arquivo app/Models/User.php:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

Sem esse trait, não é possível gerar tokens.

Passo 5 – Proteger rotas da API

Em routes/api.php:

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

Agora essa rota só pode ser acessada por usuários autenticados via Sanctum.

Conclusão

O Laravel Sanctum é uma solução poderosa e simples para autenticação moderna em APIs e SPAs. Ele elimina complexidades desnecessárias e cobre a maioria dos casos reais de mercado.

Se você precisa:

• Proteger APIs

• Integrar com frontend moderno

• Trabalhar com tokens de forma segura

👉 O Sanctum é a escolha certa.