Quelle longueur doit avoir une clé API ?

Pour une nouvelle clé API opaque, utilisez au moins 128 bits d’aléa imprévisible ; 256 bits aléatoires constituent un choix par défaut robuste lorsque le système récepteur les accepte. Cela ne signifie pas que chaque clé doit comporter 256 caractères. La même valeur de 256 bits se représente par 64 caractères hexadécimaux, 43 caractères Base64URL sans remplissage, 44 caractères Base64 avec remplissage ou 52 caractères Base32 sans remplissage.

Utilisez le Générateur de clés API ClockTools pour choisir d'abord l'entropie visée, puis le format. L'outil calcule le nombre d'octets et de caractères nécessaires avant toute génération : vous pouvez ainsi respecter la longueur maximale d'un champ sans confondre longueur visible et sécurité.

Quelle longueur choisir pour une clé API ?

Il n'existe pas de nombre universel de caractères, car un caractère ne représente pas une quantité fixe de sécurité. Un caractère hexadécimal représente 4 bits. Un caractère Base64URL choisi uniformément au hasard représente près de 6 bits, sauf dans le dernier groupe partiel. Un chiffre décimal représente environ 3,32 bits. L'alphabet, la méthode de génération et le nombre de choix indépendants déterminent l'espace de recherche.

Pour choisir concrètement, partez de ces repères :

La documentation Python de secrets indique que 32 octets, soit 256 bits, suffisent pour les usages courants de ce module, tout en précisant que la quantité d'aléa nécessaire évolue avec les capacités de calcul et les menaces. Cela fait de 256 bits un choix par défaut raisonnable, pas une règle magique de conformité.

Le service qui accepte la clé d'accès impose le format à respecter. Si une API existante exige 32 caractères hexadécimaux, un préfixe fixe ou un jeton fourni par le prestataire, respectez ce contrat. N'allongez pas, ne tronquez pas et ne réencodez pas une clé fournie à votre initiative.

Pourquoi l'entropie et le nombre de caractères diffèrent-ils ?

L'entropie pose une question plus pertinente que l'apparence : combien de secrets équiprobables le générateur aurait-il pu produire ? Une valeur de 128 bits générée uniformément au hasard offre 2^128 possibilités ; une valeur de 256 bits en offre 2^256. Ajouter des caractères visibles n'est utile que s'ils apportent des choix indépendants et imprévisibles.

RFC 4086 montre pourquoi cette distinction compte. Une longue sortie issue d'une graine de faible taille ou prévisible peut contenir bien moins d'information réelle que sa longueur ne le laisse croire. Par exemple, une valeur qui semble contenir 128 bits, mais qui provient d'une graine de seulement 8 bits, n'offre toujours que 256 graines possibles. La longueur ne compense pas un aléa insuffisant.

C'est aussi pourquoi Math.random(), les horodatages, les identifiants séquentiels, les noms d'utilisateur ou la concaténation de données d'appareil ne conviennent pas pour créer des secrets d'API. Dans un navigateur, MDN présente crypto.getRandomValues() comme la méthode permettant de produire des valeurs aléatoires cryptographiquement sûres. ClockTools exige cette API et n'utilise pas Math.random() en solution de repli.

Pour les alphabets de caractères, le calcul théorique est le suivant :

entropy bits = character count × log2(number of distinct characters)

Un alphabet de 62 lettres et chiffres nécessite 22 caractères indépendants pour dépasser 128 bits, et 43 pour dépasser 256 bits. Avec des chiffres uniquement, il en faut respectivement 39 et 78. Un alphabet restreint n'est pas automatiquement faible : il exige simplement davantage de caractères pour atteindre la même entropie.

Quelle est la longueur d'une clé API de 256 bits dans chaque encodage ?

L'encodage change la représentation, pas les octets aléatoires sous-jacents. L'outil ClockTools en ligne et ses tests de régression utilisent 32 octets aléatoires pour une entropie de 256 bits. Ils donnent les longueurs suivantes :

Ces nombres suivent les règles d'encodage de RFC 4648. L'hexadécimal est facile à examiner et largement accepté, mais il exige deux caractères par octet. Base64URL est plus compact et évite les caractères + et /, parfois gênants dans les URL et les noms de fichiers. Le Base64 classique peut contenir ces caractères et utilise un remplissage. Base32 ne distingue pas les majuscules des minuscules dans de nombreux usages, mais sa représentation est plus longue.

Choisissez un format que l'application réceptrice peut interpréter de manière fiable. Ne supprimez le remplissage que si le protocole l'autorise. Un alphabet compatible avec les URL ne signifie pas que l'on peut exposer la valeur dans une URL sans risque : les secrets d'API peuvent fuiter par l'historique du navigateur, les informations de provenance, les journaux de proxy inverse et les outils d'analyse.

Quand 128 bits suffisent-ils ?

Un secret opaque de 128 bits généré uniformément au hasard offre un immense espace de recherche pour les tentatives en ligne. Dans de nombreux systèmes, la limitation du nombre de requêtes, la surveillance, l'isolation des clés d'accès et la difficulté à tester les valeurs candidates rendent une recherche exhaustive impraticable. Passer à 256 bits augmente la marge de sécurité à faible coût pour la plupart des nouveaux systèmes côté serveur.

Le choix doit néanmoins respecter le modèle de menace et le contrat du système. Envisagez 256 bits si vous maîtrisez le format de la clé d'accès, si le coût de stockage est négligeable et si la clé protège un accès précieux ou durable. Une clé de 128 bits correctement générée peut convenir si un protocole impose cette taille, si la clé d'accès est de courte durée ou si un ancien champ ne peut pas contenir davantage.

Davantage de bits ne compensent pas l'exposition d'un secret. Une clé de 256 bits enregistrée dans un dépôt public peut être copiée immédiatement : nul besoin d'une attaque par force brute. Si une clé a pu fuiter, révoquez-la ou renouvelez-la, plutôt que de simplement la remplacer par une chaîne plus longue.

Un préfixe renforce-t-il une clé API ?

Non, si le préfixe est fixe ou prévisible. Des textes comme live_, test_ ou sk_ peuvent aider les personnes et les outils de détection de secrets à reconnaître une clé d'accès, mais ils n'ajoutent aucune entropie. Une valeur aléatoire de 256 bits reste composée de 256 bits aléatoires, que sa représentation commence par cinq caractères connus ou par aucun.

Les préfixes restent utiles : ils peuvent distinguer les clés de production de celles de test, indiquer une famille de clés d'accès et réduire le risque de coller une clé dans le mauvais système. Cette fonction doit rester distincte de la robustesse de l'authentification.

La même réserve vaut pour les suffixes et les identifiants publics de clés. Un identifiant public peut désigner le bon enregistrement dans la base de données sans révéler le secret, mais il ne doit pas être accepté comme preuve d'autorisation. ClockTools comptabilise les affixes fixes et les identifiants publics en dehors du total des bits aléatoires.

Quels autres critères comptent au-delà de la longueur ?

La longueur ne concerne que l'étape de création. Le guide de gestion des secrets de l'OWASP aborde le cycle de vie d'un secret : création, rotation, révocation et expiration. Les recommandations de Google Cloud sur les clés API insistent aussi sur les restrictions, l'isolation, la surveillance, l'absence d'exposition dans le code client et la rotation.

Avant de délivrer une clé de production, vérifiez les trois niveaux :

1. Aléa : générez au moins 128 bits imprévisibles avec une source cryptographiquement sûre ; privilégiez 256 bits pour une nouvelle clé opaque si le système les accepte.
2. Représentation : choisissez un encodage accepté par le destinataire ; ne comptez que la partie aléatoire, pas un préfixe ni un séparateur fixe.
3. Cycle de vie : limitez les autorisations, transmettez la clé via HTTPS, stockez-la dans un gestionnaire de secrets, évitez les journaux en clair, surveillez son utilisation, prévoyez une expiration lorsque c'est pertinent et permettez une révocation rapide.

Dans de nombreux systèmes, les clés API sont des justificatifs d'accès au porteur : quiconque possède la valeur peut exercer les droits associés. Elles servent généralement mieux à identifier une application ou un projet appelant qu'à authentifier une personne. Pour les actions sensibles d'un utilisateur, associez-les à une méthode d'authentification et d'autorisation conçue à cet effet, ou remplacez-les par celle-ci.

Comment générer la clé en toute sécurité ?

Pour générer rapidement une valeur dans votre navigateur, ouvrez le Générateur de clés API, conservez une entropie de 256 bits et choisissez le format requis. Le réglage Base64URL par défaut produit 32 octets aléatoires représentés par 43 caractères. La génération et la préparation de l'export se déroulent localement dans le navigateur ; la page exclut volontairement les valeurs secrètes des paramètres partagés.

Pour une infrastructure de production, générez si possible la clé dans l'environnement de confiance qui stockera le secret. Node.js crypto.randomBytes, Python secrets ou OpenSSL peuvent éviter un transfert par le presse-papiers. La page ClockTools affiche les commandes correspondantes sans y intégrer de clé générée.

Après la génération, enregistrez la valeur auprès de l'application qui la vérifiera. Une chaîne aléatoire ne devient pas une clé d'accès opérationnelle simplement parce qu'elle ressemble à une clé API. Les autorisations, l'expiration, la révocation et la vérification des requêtes relèvent du système récepteur. La méthodologie ClockTools de génération des clés API explique la source d'aléa du navigateur, l'échantillonnage par rejet, les longueurs testées et les limites ; le Générateur de GUID permet de créer des identifiants qui ne sont pas des secrets partagés.