Qu'est-ce qu'une clé API ? Définition, usage et sécurité

Qu'est-ce qu'une clé API ?

Une clé API (API key) est une chaîne secrète qui identifie l'application ou l'utilisateur appelant une API. Le serveur la recherche à chaque requête pour savoir qui appelle, quelles limites s'appliquent et quoi facturer. C'est la forme la plus simple d'authentification d'API, mais c'est un unique secret partagé : celui qui détient la clé peut agir comme son propriétaire.

Comment fonctionne une clé API

Le fournisseur génère une longue clé aléatoire et ne l'affiche qu'une fois. Le client la conserve et l'envoie à chaque requête, le plus souvent dans un en-tête. Le serveur la compare à ce qu'il a stocké, puis autorise, limite ou refuse l'appel.

GET /v1/orders HTTP/1.1
Host: api.example.com
X-API-Key: sk_live_EXAMPLE_NOT_A_REAL_KEY

Les recommandations OWASP sur la sécurité des API REST indiquent que les clés d'API et les jetons ne doivent pas figurer dans l'URL, car elle peut être enregistrée dans les journaux du serveur web.

Générer et stocker les clés

Traitez une clé comme un mot de passe. Générez-la à partir d'une source aléatoire cryptographiquement sûre, montrez-la une seule fois à l'utilisateur et ne stockez qu'un hash côté serveur. Un hash rapide comme SHA-256 suffit pour une longue clé aléatoire, et même si votre base fuite, l'attaquant ne peut pas utiliser les clés.

import crypto from 'crypto';

const key = 'sk_live_' + crypto.randomBytes(24).toString('hex');
const hash = crypto.createHash('sha256').update(key).digest('hex');

// show `key` to the user once, store only `hash` in the database
await db.apiKeys.insert({ userId, keyHash: hash });

Clé API, OAuth et JWT

Une clé API identifie une application, pas une personne, et elle expire rarement d'elle-même. C'est pourquoi l'OWASP déconseille de s'appuyer uniquement sur des clés d'API pour protéger des ressources sensibles ou de grande valeur.

Bonnes pratiques de sécurité pour les clés API

• Gardez les clés secrètes. Ne les versionnez jamais dans git, ne les collez pas dans un ticket et ne les capturez pas en image. Chargez-les depuis des variables d'environnement ou un gestionnaire de secrets.
• Utilisez des clés distinctes par environnement et par intégration, pour qu'une fuite ait une portée limitée.
• Donnez à chaque clé le minimum de droits, par exemple en lecture seule.
• Limitez l'endroit où elle fonctionne avec une liste d'adresses IP ou d'origines autorisées, si le fournisseur le permet.
• Renouvelez-la régulièrement et au moindre soupçon. Émettez la nouvelle clé, acceptez les deux pendant un court chevauchement, basculez les clients, puis révoquez l'ancienne.
• Limitez et journalisez l'usage par clé pour que les abus et les fuites apparaissent comme des anomalies. Voir abus d'API.
• Utilisez toujours HTTPS, pour que la clé soit protégée pendant le transport.

Erreurs courantes avec les clés API

• Intégrer une clé serveur dans du JavaScript front-end ou dans une application mobile, où n'importe qui peut l'extraire.
• Laisser une clé dans l'historique git. Supprimer le fichier ne l'efface pas : renouvelez la clé.
• Envoyer les clés dans les URL, que les proxys, les navigateurs et les outils d'analyse enregistrent.
• Utiliser une seule clé toute-puissante pour tous les services et environnements.
• Stocker les clés en clair dans la base au lieu de leurs hashes.
• Partager des clés par messagerie ou par e-mail au lieu d'un coffre-fort de secrets.

Tester et surveiller des API qui utilisent des clés

Les clés influencent la manière de tester une API. Utilisez une clé de test dédiée, si possible contre un environnement de préproduction, pour qu'un test de charge ne consomme pas un quota de production et ne déclenche pas la limite d'un vrai client. Si le fournisseur limite les requêtes par clé, une seule clé atteindra cette limite bien avant vos serveurs : vérifiez donc d'abord de quelle limite il s'agit. L'article sur les causes courantes de limitation de débit d'API en parle, et comment tester la charge d'API REST avec LoadFocus détaille un premier test (articles en anglais).

Vous pouvez ajouter l'en-tête de la clé à une requête ponctuelle avec l'outil curl en ligne gratuit, et à des contrôles planifiés avec la surveillance d'API de LoadFocus, qui prend en charge les en-têtes personnalisés et exécute des contrôles toutes les 5 minutes dans l'offre gratuite. Pour les endpoints qu'une clé déverrouille, voir endpoint d'API, et pour la vue d'ensemble sécurité des API.

Questions fréquentes sur les clés API

Les clés API sont-elles sûres ?

Elles sont plus faibles qu'OAuth 2.0 ou que le TLS mutuel, car un seul secret constitue toute la preuve. Elles restent acceptables pour un usage de serveur à serveur à faible risque, avec HTTPS, des droits restreints, des limites de débit et un renouvellement régulier.

Quelle est la différence entre une clé API et un bearer token ?

Une clé API identifie une application et reste en général valable jusqu'à ce que vous la renouveliez. Un bearer token est un justificatif, souvent de courte durée et lié à un utilisateur et à un scope, émis par un flux comme OAuth 2.0. Beaucoup d'API acceptent les deux dans le même en-tête.

Comment renouveler une clé API ?

Créez une nouvelle clé, faites accepter les deux par l'API pendant une période de transition, basculez tous les clients vers la nouvelle, puis révoquez l'ancienne.

Où stocker les clés API ?

Dans un gestionnaire de secrets ou des variables d'environnement côté serveur, jamais dans le code source ni dans une application cliente. Côté fournisseur, ne stockez qu'un hash.

Peut-on utiliser une clé API dans une application mobile ?

Elle peut être extraite du binaire de l'application : considérez-la comme publique. Restreignez-la autant que le fournisseur le permet, ou faites passer les appels par votre propre backend et gardez-y la vraie clé.

Comment détecter une clé API qui a fuité ?

Lancez un scanner de secrets comme GitHub secret scanning ou gitleaks sur vos dépôts et leur historique, et surveillez l'usage par clé à la recherche de volumes ou de provenances inhabituels. Renouvelez toute clé qui a fuité.