Clé API vs JWT vs OAuth2 : choisissez la bonne authentification pour votre API

Vous créez une API. Les points finaux fonctionnent. Les données circulent. Maintenant tu dois répondre à une question question avant l'expédition : comment les appelants prouvent-ils qui ils sont ?

Trois approches dominent l'authentification API : les clés API, les JWT et OAuth2. Chacun résout un problème différent. Choisissez le mauvais et vous allez soit sur-concevoir une intégration simple ou laisser une faille de sécurité dans un problème complexe.

Ce guide compare les trois sur sept critères, avec des exemples de code fonctionnel, une décision et des recommandations claires basées sur le cas d'utilisation de votre API.

Authentification par clé API : l'approche directe

Une clé API est une longue chaîne aléatoire qui identifie et autorise l'appelant. Le client envoie à chaque requête, le serveur la recherche, et si elle correspond à une clé valide, la requête passe par.

Voici à quoi ressemble un appel de clé API avec l'API botoi :

# API key in a custom header
curl -s -X POST https://api.botoi.com/v1/dns/lookup \\
  -H "Content-Type: application/json" \\
  -H "x-api-key: your_api_key_here" \\
  -d '{"domain": "example.com", "type": "A"}'

Réponse:

{
  "success": true,
  "data": {
    "domain": "example.com",
    "type": "A",
    "records": [
      { "type": "A", "value": "93.184.216.34", "ttl": 86400 }
    ]
  }
}

La x-api-key l’en-tête porte les informations d’identification. Aucun token à négocier, aucune redirection, pas de serveurs d'autorisation. Un en-tête, une recherche, une réponse.

Quand les clés API gagnent

• Appels de serveur à serveur. Votre backend appelle un autre backend. Aucun utilisateur n'est impliqué. Une tâche cron interroge une API de géolocalisation IP. Un pipeline CI exécute des vérifications DNS. L'appelant est toujours un serveur de confiance.
• API utilitaires. API qui effectuent des opérations sans état (hachage, codage, validation, recherches) où chaque requête est indépendante. botoi utilise des clés API pour cette raison : Plus de 150 points de terminaison, tous sans état, tous de serveur à serveur.
• Intégration rapide. Un développeur copie la clé, ajoute un en-tête et démarre appeler. Pas de danse OAuth, pas de logique d'actualisation de jeton, pas de point de terminaison JWKS à configurer.

Voici le même appel dans Node.js :

const response = await fetch("https://api.botoi.com/v1/hash", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BOTOI_API_KEY,
  },
  body: JSON.stringify({ text: "hello world", algorithm: "sha256" }),
});

const result = await response.json();
// result.data.hash = "b94d27b9934d3e08..."

Là où les clés API sont insuffisantes

• Aucune identité d'utilisateur. Une clé API identifie le compte, pas l'utilisateur. Si trois développeurs partagent une clé, vous ne pouvez pas savoir qui a fait quelle demande.
• La révocation nécessite un aller-retour. Révoquer une clé signifie mettre à jour celle du serveur magasin de clés. Jusqu'à l'actualisation du cache, l'ancienne clé fonctionne toujours.
• Pas d'accès délégué. Vous ne pouvez pas donner à une application tierce un accès limité et temporaire accéder aux ressources d'un utilisateur avec une seule clé API.

Authentification JWT : sessions utilisateur sans état

Un jeton Web JSON (JWT) est un objet JSON signé qui contient des revendications sur l'appelant. L'authentification le serveur le crée lors de la connexion ; le client l'envoie à chaque demande ; le serveur de ressources vérifie la signature sans appeler à nouveau le serveur d'authentification.

// Header
{
  "alg": "RS256",
  "typ": "JWT"
}

// Payload
{
  "sub": "user_12345",
  "email": "dev@example.com",
  "role": "admin",
  "iat": 1775000000,
  "exp": 1775000900   // 15 minutes
}

// Signature
RSASHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  privateKey
)

Le serveur vérifie la signature avec la clé publique. Si la signature est vérifiée et exp n'est pas passé, la demande est autorisée. Aucune recherche dans la base de données n'est nécessaire.

Quand les JWT gagnent

• API destinées aux utilisateurs avec un trafic élevé. Une application mobile envoie un JWT à chaque fois demande. La passerelle API vérifie la signature localement au lieu d'interroger un magasin de sessions à chaque appel. À 10 000 requêtes par seconde, cet appel de base de données vous a échappé.
• Architectures de microservices. Le service A appelle le service B avec un JWT. Prestation B le valide localement et extrait l'ID et les rôles de l'utilisateur des revendications. Pas de session partagée base de données entre les services.
• Autorisation de courte durée. Un jeton de 15 minutes pour un téléchargement de fichier. Une 5 minutes jeton pour une confirmation de paiement. L'expiration est intégrée au jeton lui-même.

Voici le middleware Express qui vérifie un JWT :

import jwt from "jsonwebtoken";

function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return res.status(401).json({ error: "Missing token" });

  try {
    const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY, {
      algorithms: ["RS256"],
    });
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(401).json({ error: "Invalid or expired token" });
  }
}

Là où les JWT échouent

• La révocation des jetons est difficile. Un JWT est valide jusqu'à son expiration. Si un utilisateur se connecte ou vous devez révoquer l'accès, vous avez besoin d'une liste de blocage côté serveur, qui ramène le appel à la base de données que vous essayiez d'éviter.
• Taille de la charge utile. Chaque réclamation ajoute des octets. Un JWT avec des rôles d'utilisateur, des autorisations, et les métadonnées peuvent atteindre 1 à 2 Ko. Cela représente 1 à 2 Ko sur chaque requête, dans chaque en-tête.
• Complexité de la rotation des clés. Lorsque vous faites pivoter les clés de signature, les anciens jetons signés avec la clé précédente doivent rester valides jusqu'à leur expiration. Cela signifie servir plusieurs clés publiques via un point de terminaison JWKS et gérer les kid revendication d'en-tête.

OAuth2 : accès délégué pour les tiers

OAuth2 est un cadre d'autorisation, pas un protocole d'authentification. Il permet à un utilisateur d'accorder un application tierce limitant l'accès à ses ressources sur un autre service, sans partage leur mot de passe.

L'exemple classique : un utilisateur autorise un outil de gestion de projet à lire son GitHub référentiels. L'utilisateur se connecte à GitHub, approuve des étendues spécifiques et l'outil reçoit un jeton d’accès limité à ces autorisations.

# Step 1: Redirect user to authorization server
GET https://auth.example.com/authorize?
  response_type=code&
  client_id=your_app_id&
  redirect_uri=https://yourapp.com/callback&
  scope=read:repos+write:issues&
  state=random_csrf_token

# Step 2: Exchange authorization code for tokens
POST https://auth.example.com/token
  grant_type=authorization_code&
  code=AUTH_CODE_FROM_CALLBACK&
  client_id=your_app_id&
  client_secret=your_app_secret&
  redirect_uri=https://yourapp.com/callback

# Step 3: Call the API with the access token
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \\
  https://api.example.com/v1/repos

Quand OAuth2 gagne

• Intégrations tierces. Vous exploitez une plateforme et souhaitez des développeurs externes pour créer des applications qui accèdent aux données de vos utilisateurs. OAuth2 donne aux utilisateurs le contrôle sur ce que chaque application peut accéder.
• Lunettes à grain fin. read:repos mais pas delete:repos. write:issues mais pas admin:org. OAuth2 les étendues permettent aux utilisateurs d’approuver des autorisations spécifiques.
• Flux « Connectez-vous avec X ». Lorsque votre application utilise Google, GitHub ou Microsoft pour login, vous utilisez OAuth2 (souvent avec OpenID Connect en haut) pour obtenir un jeton d'identité.

Là où OAuth2 échoue

• Complexité. OAuth2 a quatre types d'octroi, jetons d'actualisation, autorisation serveurs, URI de redirection, PKCE et points de terminaison d'introspection de jetons. Pour une API utilitaire avec pas de contexte utilisateur, c'est une surcharge sans aucun avantage.
• Friction d’intégration. Un développeur qui souhaite appeler votre point de terminaison de hachage ne souhaite pas enregistrer une application OAuth, configurer des URI de redirection et échanger des autorisations codes. Ils veulent une clé et une commande curl.
• Charge de gestion des jetons. Les jetons d'accès expirent. Les jetons d’actualisation tournent. Les clients ont besoin d'une logique de nouvelle tentative pour les réponses 401. Pour de simples appels de serveur à serveur, il s'agit de des machines inutiles.

Tableau comparatif

Critères	Clé API	JWT	OAuth2
Temps d'intégration	Minutes	Heures	Jours
Identité de l'utilisateur	Au niveau du compte	Au niveau de l'utilisateur (réclamations)	Niveau utilisateur (portées)
Vérification apatride	Non (recherche de serveur)	Oui (vérification de signature)	Dépend du format du jeton
Vitesse de révocation	Immédiat (supprimer la clé)	Différé (jusqu'à expiration)	Immédiat (révoquer le jeton)
Accès délégué	Non	Non	Oui
Assistance tierce	Pauvre	Bien	Excellent
Convient aux navigateurs	Non (exposition clé)	Oui (de courte durée)	Oui (code d'autorisation + PKCE)

Cadre de décision : choisissez en fonction de votre cas d'utilisation

Arrêtez de demander « qu'est-ce qui est le plus sécurisé ? » Tous les trois sont sécurisés lorsqu’ils sont utilisés correctement. Le droit question : "qui appelle mon API et pourquoi ?"

• Le serveur appelle le serveur, aucun utilisateur impliqué : Clé API. Votre backend appelle un API utilitaire pour les recherches DNS, le hachage ou la validation des données. Une clé, un en-tête, c'est fait.
• Votre propre application authentifie vos propres utilisateurs : JWT. Votre application mobile ou SPA envoie des requêtes au nom d'un utilisateur connecté. Signez un JWT de courte durée lors de la connexion, vérifiez-le à chaque demande sans magasin de session.
• Les applications tierces accèdent aux données des utilisateurs : OAuth2. Construction de développeurs externes intégrations avec votre plateforme. Les utilisateurs contrôlent ce à quoi chaque application peut accéder via la portée écrans de consentement.

Gérer les clés API à grande échelle avec Unkey

Les clés API semblent simples jusqu'à ce que vous deviez les hacher, appliquer des limites de débit, définir l'expiration dates, suivez l'utilisation par clé et faites-les pivoter sans temps d'arrêt. Construire tout cela à partir de le scratch prend des semaines.

Désactiver la clé est un ouvert service de gestion des clés d'API source qui gère la création, la vérification, la limitation du débit et analytique. botoi utilise Unkey pour gérer toutes les clés API sur ses plus de 150 points de terminaison.

Créez une clé étendue avec une limitation de débit intégrée :

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY });

// Create a scoped API key with built-in rate limiting
const key = await unkey.keys.create({
  apiId: "api_your_api_id",
  prefix: "botoi",
  meta: { userId: "user_12345", plan: "pro" },
  expires: Date.now() + 90 * 24 * 60 * 60 * 1000, // 90 days
  ratelimit: {
    type: "fast",
    limit: 100,
    refillRate: 10,
    refillInterval: 1000,
  },
});

// key.result.key = "botoi_3xK9m2..."

Vérifiez-le dans votre middleware :

import { verifyKey } from "@unkey/api";

async function authMiddleware(req, res, next) {
  const apiKey = req.headers["x-api-key"];
  if (!apiKey) return res.status(401).json({ error: "Missing API key" });

  const result = await verifyKey(apiKey);

  if (!result.result.valid) {
    return res.status(result.result.code === "RATE_LIMITED" ? 429 : 403)
      .json({ error: result.result.code });
  }

  req.keyMeta = result.result.meta; // { userId, plan }
  next();
}

Unkey stocke les clés hachées (jamais en texte brut), applique les limites de débit en périphérie et donne vous obtenez un tableau de bord analytique montrant l'utilisation par clé. Lorsqu'une clé nécessite une rotation, créez-en une nouvelle et fixez une date d'expiration à l'ancien. Pas de temps d'arrêt, pas de changement de code.

Liste de contrôle de sécurité pour chaque approche

Clés API

• Envoyez via HTTPS uniquement. N'intégrez jamais de clés dans des URL ou des chaînes de requête.
• Stockez le hachage sur le serveur. N’enregistrez jamais les clés brutes.
• Étendez les clés à des autorisations spécifiques (lecture seule, écriture, administrateur).
• Fixez les dates d’expiration. Forcer la rotation tous les 90 jours.
• Utilisez un en-tête personnalisé (x-api-key) au lieu de Authorization à évitez la mise en cache des informations d’identification du navigateur.

JWT

• Utilisez la signature asymétrique (RS256 ou ES256). N'utilisez jamais HS256 avec un secret partagé dans systèmes distribués.
• Gardez la durée de vie des jetons courte : 5 à 15 minutes pour les jetons d'accès.
• Valider iss, aud, et exp réclamations sur chaque demande.
• Publiez des clés publiques via un point de terminaison JWKS. Faites pivoter les clés de signature selon un calendrier.
• Ne stockez jamais de données sensibles dans la charge utile. Les JWT sont codés et non chiffrés.

OAuth2

• Utilisez le flux de code d'autorisation avec PKCE pour tous les clients, y compris les SPA et les appareils mobiles. applications.
• N’utilisez jamais le flux implicite. Il est obsolète dans OAuth 2.1 pour une bonne raison.
• Stockez les secrets client sur le serveur uniquement. Ne les envoyez jamais dans des applications mobiles ou frontend code.
• Valider state paramètres pour empêcher les attaques CSRF sur l’URL de rappel.
• Utilisez des jetons d’accès de courte durée avec une rotation des jetons d’actualisation.

Points clés

• Clés API sont le bon choix pour les API d’utilitaires serveur à serveur. Ils sont rapide à intégrer, facile à gérer et suffisant lorsqu’aucune identité utilisateur n’est nécessaire. botoi les utilise sur plus de 150 points de terminaison avec Unkey pour la gestion.
• JWT sont le bon choix pour les sessions utilisateur sans état. Ils éliminent recherches de magasins de sessions à grande échelle, mais la révocation de jetons nécessite une infrastructure supplémentaire.
• OAuth2 est le bon choix lorsque les applications tierces ont besoin d'un accès limité à ressources des utilisateurs. La complexité est justifiée par le modèle de sécurité qu’il propose.
• Choisissez en fonction de l'appelant et non du battage médiatique. Une API utilitaire avec OAuth2 est sur-conçue. Un L'API de la plate-forme avec uniquement des clés API ne peut pas accorder un accès délégué.
• Combinez les approches lorsque votre produit l’exige. Clés API pour les intégrations directes, OAuth2 pour les partenaires du marché, JWT pour les sessions utilisateur connectées.