API route Next.js : authentification, session et protection

Confier au client la logique d’auth, c’est le genre d’erreur qu’on retrouve encore en audit sur des apps déployées. La règle tient en une ligne : chaque API route valide session ou token côté server, le middleware reste un garde-fou UX. Derrière ce choix, trois sujets réels : latence, sécurité, contrôle d’accès.

Qu’est-ce que api route next js authentification ?

API route Next.js authentification désigne l’ensemble des mécanismes pour vérifier qu’un user est bien celui qu’il prétend être avant d’exécuter la logique d’une route. Dans Next, une route peut être une pages/api, un route handler de l’App Router, ou un endpoint intercepté par middleware. L’enjeu est d’authentifier le user, d’autoriser l’action et de maintenir une session ou un token sécurisés.

• Authentication : prouve l’identité d’un user.
• Auth (contraction fréquente) : ensemble des fonctions d’authentication et d’autorisation.
• Authorization : vérifie si un user authentifié peut exécuter une action.

Un request arrive au server, le server lit cookies ou headers, vérifie la session ou le token, et décide de retourner 200, 401 ou 403 selon le cas. Cette logique s’applique aussi bien avec Auth0 qu’avec une solution custom.

Authentication, auth et authorization : quelle différence ?

Authentication répond à « qui êtes-vous ? ». Authorization répond à « que pouvez-vous faire ? ». Une session valide prouve l’authentication, mais ne donne pas automatiquement l’autorisation à accéder à une route admin. Il faut vérifier les claims du user. Dans une route Next.js on lit la session, on extrait le user, puis on checke les rôles.

Pourquoi protéger une route côté server plutôt que côté client ?

Le client peut masquer ou modifier son état. Une API route qui ne vérifie pas la session ou le token expose les données. Protéger côté server empêche l’accès direct via curl ou via un client malveillant. Middleware améliore l’expérience avec des redirect pour les pages, mais la règle simple reste : chaque route server doit vérifier l’authentication.

Pages, app et routes : les bases à connaître avant de coder

Deux routes serveur coexistent : pages/api (pages router) et route handlers (App Router). Les deux tournent sur Node ou Edge selon la configuration.

pages/api ou App Router route handlers : que choisir ?

Choix pragmatique selon le cas d’usage :

• pages/api : compatibilité, simplicité pour des projets existants, facile à brancher sur Auth0 via callbacks.
• App Router route handlers : meilleure intégration avec edge, meilleure latence pour les users internationaux, et possibilité de combiner server actions.

Le trade-off porte sur la latence et l’infrastructure. Pour un produit SaaS à audience internationale, un route handler en edge avec validation de cookie courte améliore le TTFB. Pour un backend centralisé, pages/api reste pertinent.

Quand utiliser middleware pour l’authentification ?

Middleware sert à intercepter requests avant qu’elles n’atteignent page ou route. Utilisez middleware pour :

• Rediriger un user non connecté vers la page de login.
• Ajouter headers communs, vérifier un cookie simple, ou recalculer une route de langue. Mais le middleware doit rester léger. Ne mettez pas toute la logique métier dans le middleware. Le middleware peut lire un cookie, faire un lookup minimal et redirect ou laisser passer. Ensuite, la route handler relit et confirme la session.

Quand protéger une page plutôt qu’une route ?

Protéger une page via middleware améliore UX : on redirecte vers /login quand l’user n’est pas auth. En revanche, une API route doit toujours renvoyer 401/403 et ne pas redirect. Protéger une page évite d’afficher des éléments UI pour un user non connecté, mais n’exonère pas la route d’un check côté server.

Server actions : utile ou non pour l’auth ?

Server actions exécutent du code server depuis le composant. Elles suffisent pour des opérations fortement liées à l’UI. Dès qu’un endpoint est consommé par plusieurs clients ou exposé à des tiers, on retombe sur une route handler avec checks explicites de session ou de token.

Impact TTFB et latence à l’edge

La vérification d’un cookie signé est souvent plus rapide que la vérification d’un JWT volumineux. Placer la vérification à l’edge réduit le round-trip. Le middleware à l’edge peut effectuer un check minimal pour rediriger ou rejeter, puis la route handler, sur le server, fait la vérification complète incluant les claims pour l’autorization.

Exemple de route handler protégé dans Next.js

Route handler App Router qui lit un bearer token et répond 200, 401 ou 403.

import { NextResponse } from "next/server";
import { verifyToken } from "@/lib/auth"; // utilitaire de verification

export async function GET(request) {
  const authHeader = request.headers.get("authorization") || "";
  const token = authHeader.replace("Bearer ", "");
  if (!token) {
    return new NextResponse(JSON.stringify({ error: "Unauthorized" }), { status: 401 });
  }

  try {
    const user = await verifyToken(token);
    if (!user) {
      return new NextResponse(JSON.stringify({ error: "Forbidden" }), { status: 403 });
    }
    return new NextResponse(JSON.stringify({ user }), { status: 200 });
  } catch (error) {
    return new NextResponse(JSON.stringify({ error: "Invalid token" }), { status: 401 });
  }
}

Ce pattern montre comment lire la request, extraire le token, vérifier le user et renvoyer 401 ou 403 selon le contexte. On préfère 401 pour absence de credential, 403 pour manque de permission.

Lire la session depuis cookies

Lire la session depuis cookies est courant avec Auth0 ou NextAuth.js. En route handler on lit request.headers.get("cookie"), parse la cookie, et vérifie la session côté server. La session peut être stockée côté server ou dans un cookie signé. Avec auth0, on utilise souvent un cookie de session et on valide le token via la librairie du provider.

Exemple minimal :

import { parse } from "cookie";
const cookies = parse(request.headers.get("cookie") || "");
const sessionCookie = cookies["app.session"];
if (!sessionCookie) return new NextResponse(null, { status: 401 });
const session = await decodeSession(sessionCookie);

Lire et vérifier un bearer token

Les bearer tokens arrivent dans l’header Authorization. Pour une route REST, on lit le header, on extrait le token, et on appelle la fonction de vérification. Les erreurs doivent être traitées avec soin : token absent → 401, token invalide → 401, token valide mais claims insuffisantes → 403.

Retourner 401 ou 403 selon le contexte

• 401 Unauthorized : absence ou invalidité des credentials, demander à l’user de se reconnecter.
• 403 Forbidden : user authentifié mais sans permission pour l’action.

Pour une API route on n’effectue pas de redirect ; on renvoie le code HTTP approprié. Pour une page, on peut redirect vers /login.

Créer une route de login avec POST

Une route de login POST reçoit email/password, vérifie via auth0 ou via une base propre, crée une session et renvoie un cookie sécurisé. Exemple schématique :

import { signSessionCookie } from "@/lib/session";
export async function POST(request) {
  const body = await request.json();
  const { email, password } = body;
  const user = await authService.login(email, password); // wrapper vers auth0 ou DB
  if (!user) return new Response(null, { status: 401 });
  const cookie = signSessionCookie({ sub: user.id });
  return new Response(JSON.stringify({ user }), {
    status: 200,
    headers: { "Set-Cookie": cookie }
  });
}

Dans cet exemple, la function login peut appeler auth0, ou gérer la vérification en interne. L’important est le Set-Cookie sécurisé.

Exemple de réponse JSON sécurisée

Preferer une réponse minimale : { user: { id, email }, meta: { expiresAt } }. Ne pas exposer de tokens privés ni d’informations sensibles.

Middleware et protection des routes Next.js

Le middleware permet d’intercepter requests avant qu’elles atteignent la page ou la route. Il est parfait pour rediriger un user non connecté, mais il ne doit pas exécuter toute la logique métier.

Exemple d’usage :

• Vérifier un cookie de session.
• Si absent, faire un redirect vers /login.
• Si présent, laisser passer et ajouter un header x-user-id.

La logique de vérification complète des claims et des permissions reste dans la route handler.

Rediriger un user non connecté vers login

Pour les pages, middleware peut effectuer un redirect HTTP. Le redirect améliore l’UX sur le client. Pour une API route, renvoyer 401 est la bonne pratique.

Bloquer un user sans rôle admin

Dans middleware on peut intercepter une route commençant par /admin et vérifier un claim minimal. Mais la route admin doit redoubler la vérification côté handler. Produire un header indiquant le rôle peut aider le server à décider.

Pourquoi le middleware ne suffit pas seul

Le middleware peut être contourné ou peut ne pas avoir accès à toutes les informations nécessaires. Il sert d’optimisation et de premier gate, pas de contrôle d’accès final. On garde la logique métier d’autorization dans les routes.

Auth0 pour Next.js : cas d’usage et limites

Auth0 accélère l’implémentation d’authentication, fournit des providers standardisés et gère lifecycle de sessions. Avec auth0 on obtient un flux de login, logout, callbacks, refresh token et user management. auth0 s’intègre à Next via des SDK ou via un provider custom.

Limites à connaître :

• Dépendance à un tiers, donc penser à la disponibilité et au coût.
• Il faut toujours vérifier localement les claims dans chaque route sensible.
• auth0 gère le token, mais on doit vérifier la validité du token dans la route.

On peut intégrer auth0 dans une pages/api ou dans un route handler. Souvent, une seule API route suffit pour les callbacks et sessions avec auth0.

Authgear pour sécuriser les route handlers

Authgear est une alternative adaptée aux route handlers quand on veut un contrôle fin sur les endpoints. Comme pour auth0, l’idée est de déléguer l’authentication tout en gardant la vérification des claims dans la route.

NextAuth.js pour centraliser providers et session

NextAuth.js centralise providers, session et callbacks dans une seule API route. NextAuth.js facilite la mise en place d’authentication et la création de sessions côté Next. En pratique, NextAuth.js crée une API route qui gère login, callback, session et logout.

Quel choix pour une app web ou un produit SaaS ?

Pour un MVP, NextAuth.js ou auth0 réduisent le temps d’implémentation. Pour un produit SaaS avec besoins avancés de RBAC, combiner auth0 avec des checks supplémentaires côté server est souvent la voie la plus sûre.

Pour l’architecture liée au state client, voir notre article sur le state management si la gestion du user influe sur l’UI : on peut lier la session server à un store côté client via cookies sécurisés et hydratation serveur / client en synchronisant avec /state-management-react-zustand/.

(Plus loin on évoque l’importance d’un framework moderne ; pour un panorama des options, consulter le rapport sur les frameworks JavaScript : /framework-javascript-2026/.)

RBAC dans une API route Next.js

RBAC exige que la route vérifie les claims du user. Exemple de check :

if (!user.roles || !user.roles.includes("admin")) {
  return new NextResponse(null, { status: 403 });
}

Vérifier les claims du user

Les claims viennent du token ou de la session, jamais d’un champ posté par le client. On les extrait du token validé, puis on applique les règles métier.

Limiter l’accès aux routes admin

Séparer les endpoints admin dans un préfixe /api/admin et appliquer middleware pour vérifier la présence d’un token admin. Puis dans chaque handler, revérifier les claims.

Différence entre utilisateur authentifié et autorisé

Un user authentifié a prouvé son identité. Un user autorisé a la permission d’exécuter l’action. Les deux étapes se font dans la route, pas ailleurs.

Pourquoi renvoyer 401 au lieu d’une redirection dans une API route ?

Une API route est consommée par des clients qui attendent un code HTTP. Les redirect ne sont pas pertinents ; un 401 indique au client qu’il doit redemander une authentication ou relancer un flow de login. Pour les pages, redirecter vers /login améliore l’expérience.

Quand renvoyer 403 Forbidden ?

Le 403 signale un user authentifié mais sans droit sur l’action demandée. Le corps reste minimal pour ne pas divulguer d’informations sur le modèle d’autorisation.

Gérer CORS et l’Origin header

Next.js ne configure pas automatiquement CORS sur les route handlers. Un handler consommé en cross-origin doit lire l’Origin header, comparer à une allowlist, et renvoyer 401 quand l’Origin n’y figure pas.

Erreurs fréquentes avec cookies et token expiré

• Ne pas vérifier la présence d’un cookie secure. Toujours set-cookie avec Secure, HttpOnly et SameSite.
• Oublier de gérer la rotation de refresh token.
• Accepter un token expiré sans refresh.

En production, prévoir un handler qui renvoie 401 pour token expiré et guide le client vers le login ou le refresh.

Erreurs courantes dans api route next js authentification

On observe souvent : faire confiance au client, placer toute la logique d’auth dans le middleware, oublier de renvoyer 401/403 corrects, exposer des données sensibles dans la réponse, et mélanger protection page et protection API.

Checklist de sécurité avant mise en production

• Vérifier que chaque route API valide une session ou un token.
• Vérifier que les routes admin revérifient les claims.
• S’assurer que les cookies sont Secure, HttpOnly, et SameSite approprié.
• Tester le comportement CORS et l’Origin header.
• Confirmer que le middleware ne remplace pas la logique métier.

Quand relire votre architecture d’authentification ?

Reprendre la conception quand vous ajoutez un nouveau type de client (mobile, third-party), quand la latence impacte le TTFB, ou quand le modèle d’autorization devient plus complexe.

Quiz personnalisé

Votre recommandation sur api route next.js

Trois questions rapides pour savoir exactement ce qui s'applique dans votre situation.

Q1 Quel est votre rôle dans la situation ?

Conducteur identifié Titulaire du véhicule Entreprise / société Témoin / tiers

Q2 Quel type de situation ?

Je viens d'être verbalisé Je conteste une amende Je cherche à comprendre la loi Je prépare un examen

Q3 Quelle est votre priorité ?

Éviter les points en moins Économiser (éviter l'amende) Gagner du temps Maîtriser mes droits

Voir ma recommandation

Résultat instantané, pas de création de compte.