Sanctum est souvent présenté comme "l'authentification simple pour API Laravel", ce qui pousse beaucoup d'équipes à l'installer sans comprendre qu'il couvre en réalité deux mécanismes distincts, avec des modèles de sécurité différents. Les confondre est la source la plus fréquente de failles ou de bugs d'authentification difficiles à diagnostiquer en production.
Deux mécanismes, pas un
Sanctum gère deux cas d'usage séparés, documentés comme tels mais souvent utilisés sans distinction claire dans le code :
- Les tokens d'API (
personal access tokens) : un token opaque stocké en base, envoyé dans un headerAuthorization: Bearer, pensé pour des clients tiers, des mobiles, ou des intégrations machine-to-machine qui n'ont pas de notion de session navigateur. - L'authentification SPA par cookie : pas de token du tout côté client, mais le cookie de session Laravel classique, protégé par le middleware CSRF standard. Pensé pour un frontend qui partage le même domaine racine que l'API (ou un sous-domaine configuré explicitement).
Le choix entre les deux n'est pas une question de préférence, mais d'architecture : un frontend Next.js servi sur un domaine différent de l'API et consommé aussi par une app mobile doit utiliser les tokens. Un frontend Vue/Inertia servi depuis le même Laravel ou un sous-domaine du même domaine racine doit utiliser le cookie SPA.
Configurer les tokens d'API correctement
L'installation ajoute le trait HasApiTokens au modèle User, et le middleware auth:sanctum protège les routes.
// app/Models/User.php
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable
{
use HasApiTokens, Notifiable;
}
// routes/api.php
Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
return $request->user();
});
La création d'un token doit systématiquement restreindre ses capacités avec des "abilities", l'équivalent de scopes OAuth léger intégré à Sanctum :
// Génère un token qui ne peut QUE lire les commandes, jamais les modifier
$token = $user->createToken('mobile-app', ['orders:read']);
// Côté route protégée, vérifier l'ability, pas seulement l'authentification
Route::get('/orders', function (Request $request) {
if (! $request->user()->tokenCan('orders:read')) {
abort(403);
}
// ...
})->middleware('auth:sanctum');
Un piège fréquent : créer tous les tokens avec ['*'] par défaut, ce qui annule l'intérêt des abilities et transforme chaque token en clé totale sur le compte, y compris pour un token destiné à une intégration tierce qui ne devrait avoir qu'un accès en lecture.
La révocation, souvent oubliée jusqu'à l'incident
Un token Sanctum n'expire pas par défaut : il reste valide jusqu'à suppression explicite. C'est une différence importante avec un JWT classique qui expire automatiquement. Ne pas prévoir de mécanisme de révocation dès la conception, c'est se retrouver, le jour où un appareil est volé ou un employé quitte l'entreprise, sans moyen rapide de couper l'accès autrement qu'en révoquant tous les tokens de l'utilisateur.
// Révoquer un token précis (ex: déconnexion d'un seul appareil)
$request->user()->currentAccessToken()->delete();
// Révoquer tous les tokens de l'utilisateur (ex: changement de mot de passe,
// compromission suspectée)
$user->tokens()->delete();
Pour une expiration automatique, Sanctum la supporte via la configuration, mais elle n'est pas activée par défaut :
// config/sanctum.php
'expiration' => 60 * 24 * 7, // en minutes, ici 7 jours
Sans cette ligne, un token "oublié" dans le code d'une app mobile jamais mise à jour reste valide indéfiniment.
L'authentification SPA par cookie : le piège CSRF mal compris
Pour le mode SPA, Sanctum ne génère aucun token. La séquence attendue est : le frontend appelle d'abord GET /sanctum/csrf-cookie pour obtenir un cookie XSRF-TOKEN, puis chaque requête mutante (POST/PUT/DELETE) doit renvoyer sa valeur dans le header X-XSRF-TOKEN. La plupart des clients HTTP modernes (Axios en particulier) le font automatiquement si withCredentials/withXSRFToken est activé, ce qui masque le mécanisme et pousse les développeurs à ne jamais vraiment le comprendre jusqu'au jour où ça échoue en production avec un domaine différent de celui testé en local.
// Frontend - Axios
axios.defaults.withCredentials = true;
axios.defaults.withXSRFToken = true;
await axios.get("/sanctum/csrf-cookie"); // initialise le cookie XSRF-TOKEN
await axios.post("/login", { email, password });
// config/sanctum.php - domaines considérés comme "stateful"
'stateful' => explode(',', env(
'SANCTUM_STATEFUL_DOMAINS',
'localhost,127.0.0.1,app.example.com'
)),
Si le domaine du frontend n'apparaît pas dans stateful, Sanctum traite la requête comme venant d'une origine externe et refuse de créer la session, même si CORS est par ailleurs correctement configuré. C'est l'erreur de configuration la plus fréquente en production : la liste stateful est configurée en local (localhost) et jamais mise à jour avec le vrai sous-domaine de prod.
CORS et cookies : la combinaison qui échoue silencieusement
L'authentification SPA par cookie exige que CORS autorise explicitement les credentials, ce qui interdit le wildcard sur l'origine (voir l'article dédié à CORS pour le mécanisme complet) :
// config/cors.php
'supports_credentials' => true,
'allowed_origins' => ['https://app.example.com'], // jamais '*' ici
Sans supports_credentials: true, le navigateur reçoit bien une réponse, mais n'enregistre jamais le cookie de session, ce qui produit un comportement déroutant : le login semble réussir (statut 200), mais chaque requête suivante revient non authentifiée, parce que le cookie n'a jamais été stocké.
Le choix à ne jamais faire : mélanger les deux mécanismes par flux
Un piège d'architecture réel consiste à authentifier le login via cookie SPA, puis à essayer de lire $request->user() dans un contexte où seul un token Bearer est attendu (un webhook, un job en queue qui rejoue une requête). Les deux mécanismes ne sont pas interchangeables dans le même flux : un cookie de session n'a aucun sens pour un appel serveur-à-serveur, et un token Bearer n'a aucun sens pour un navigateur qui doit gérer le CSRF.
Quand Sanctum ne suffit pas
Sanctum est volontairement minimaliste : pas de scopes OAuth standard interopérables avec des clients tiers externes, pas de flux d'autorisation délégué (consentement utilisateur pour une app tierce), pas de refresh token au sens OAuth2. Pour une API qui doit exposer un vrai flux OAuth2 à des partenaires externes (un "Se connecter avec..." proposé par d'autres applications), Laravel Passport ou un fournisseur OAuth2 dédié reste le bon choix. Sanctum répond au besoin "mon propre frontend et mes propres apps mobiles s'authentifient auprès de mon API", pas au besoin "des applications tierces s'authentifient au nom de mes utilisateurs".
Où stocker le token côté client, et pourquoi ça compte
Choisir Sanctum avec des tokens Bearer déplace une partie de la responsabilité de sécurité vers le client : contrairement au cookie SPA, qui peut être marqué HttpOnly et donc rester invisible au JavaScript, un token Bearer doit être lu par le code client pour être placé dans le header Authorization, ce qui l'expose par construction à toute faille XSS de l'application.
Stocker ce token dans localStorage est l'erreur la plus répandue : n'importe quel script injecté via une faille XSS peut le lire et l'exfiltrer, sans même avoir besoin de contourner de protection CSRF puisqu'il ne s'agit pas d'un cookie. Pour une application mobile (Flutter, React Native), le token doit être stocké dans le keychain/keystore natif de la plateforme (flutter_secure_storage, expo-secure-store), jamais dans un stockage clé-valeur non chiffré accessible à n'importe quel processus avec les permissions du système de fichiers de l'app.
// Flutter - stockage correct d'un token Sanctum côté mobile
final storage = FlutterSecureStorage();
await storage.write(key: 'sanctum_token', value: token);
Pour un SPA web qui doit malgré tout utiliser des tokens (cas d'un frontend sur un domaine totalement distinct de l'API, incompatible avec le mode cookie), le compromis le moins mauvais reste de garder le token en mémoire JavaScript (une variable de module, un store applicatif) plutôt qu'en localStorage, au prix de devoir ré-authentifier l'utilisateur à chaque rechargement complet de page.
À retenir : choisir entre tokens Bearer et cookie SPA selon l'architecture réelle du frontend, jamais par défaut, restreindre systématiquement les abilities des tokens plutôt que d'utiliser ['*'], et vérifier SANCTUM_STATEFUL_DOMAINS et supports_credentials en premier dès qu'une authentification SPA fonctionne en local mais échoue en production.
