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:

/sanctum/csrf-cookie
/login
Requisições autenticadas automaticamente

🧠 Comparação rápida

Característica	Token API	SPA
Usa sessão	❌ Não	✅ Sim
Usa cookies	❌ Não	✅ Sim
Header Authorization	✅ Sim	❌ Não
CSRF	❌ Não	✅ Sim
Ideal para mobile	✅ Sim	❌ Não

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.

APIs e Laravel Sanctum

Comments

Laravel

Laravel Scheduler: Automatizando Tarefas com Commands, Jobs e Events

More from this blog

Ngrok no Linux: Guia Completo de Instalação, Configuração e Uso

Ambientação Linux com Play with Docker

Melhore sua Produtividade com Capturas de Tela no Pop!_OS usando Flameshot

Como Resolver o Erro "git@github.com: Permission denied (publickey)" ao Clonar um Repositório GitHub

Como configurar e utilizar o Tailwindcss

Introdução

Como funciona o Laravel Sanctum

🔐 Tokens pessoais (Personal Access Tokens)

🍪 Autenticação baseada em cookies (SPA)

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

🔹 Tokens de API

🔹 Autenticação SPA (Cookies)

🧠 Comparação rápida

Instalação – Passo a passo

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

Passo 2 – Publicar configurações

Passo 3 – Rodar as migrations

Passo 4 – Configurar o Model User

Passo 5 – Proteger rotas da API

Conclusão

Command Palette

Comments

Laravel

Laravel Scheduler: Automatizando Tarefas com Commands, Jobs e Events

More from this blog

Introdução

Como funciona o Laravel Sanctum

🔐 Tokens pessoais (Personal Access Tokens)

🍪 Autenticação baseada em cookies (SPA)

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

🔹 Tokens de API

🔹 Autenticação SPA (Cookies)

🧠 Comparação rápida

Instalação – Passo a passo

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

Passo 2 – Publicar configurações

Passo 3 – Rodar as migrations

Passo 4 – Configurar o Model User

Passo 5 – Proteger rotas da API

Conclusão

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