Veille

Clés API

Créez, configurez et gérez vos clés API depuis votre tableau de bord.

Les clés API authentifient vos requêtes auprès de l'API. Vous les gérez entièrement depuis API → Clés API dans le tableau de bord : définissez une catégorie, limitez l'utilisation avec des quotas glissants, ajoutez une date d'expiration et surveillez l'activité par clé dans le journal des requêtes.

Pour savoir comment inclure une clé dans une requête, consultez l'Introduction.

Créer une clé

Ouvrir le formulaire

Accédez à API → Clés API dans votre tableau de bord et cliquez sur Nouvelle clé API.

Remplir les champs

Donnez à la clé un Nom (unique dans le compte), choisissez une Catégorie dans l'onglet Options de clé API, et définissez éventuellement Expire et les Limites de requêtes.

Copier le secret

Cliquez sur Créer la clé API. La fenêtre Clé API créée affiche la clé complète avec un bouton Copier : stockez-la tout de suite dans une variable d'environnement ou un gestionnaire de secrets.

Champs de la clé

ChampDescription
NomÉtiquette unique par compte (l'alias dans certains messages d'erreur). Apparaît dans le journal des requêtes et les filtres des analyses.
CatégorieÉtiquette d'organisation (voir Catégories). N'a aucun effet sur le comportement de l'API.
ActiveActive ou désactive la clé. Les clés inactives sont rejetées immédiatement avec 401 Inactive API Key.
ExpireDate optionnelle après laquelle la clé cesse de fonctionner. Laissez vide pour ne pas avoir d'expiration.
Limites de requêtesPlafonds optionnels par clé sur des fenêtres glissantes (voir Quotas par clé).

Catégories

Les catégories étiquettent les clés pour votre organisation. Elles apparaissent dans les filtres et analyses du tableau de bord mais ne modifient pas le traitement des requêtes par l'API.

CatégorieUtilisation typique
productionTrafic en direct, systèmes orientés client
developmentDéveloppement local et tests
stagingEnvironnements de pré-production et CI
PersonnaliséeToute étiquette libre, ex. sandbox, partner-acme

Conservez une clé par environnement pour pouvoir la révoquer ou la faire tourner de façon indépendante.

Quotas par clé

Chaque clé peut avoir des plafonds indépendants sur le volume de requêtes, appliqués sur des fenêtres glissantes (pas des limites calendaires) :

QuotaFenêtre
TotalLimite globale stricte dans le tableau de bord. Depuis toujours : la clé est bloquée définitivement une fois atteint
QuotidienLimite sur fenêtre glissante de 24h. Dernières 24 heures (glissant, pas de minuit à minuit)
HebdomadaireLimite sur fenêtre glissante de 7j. 7 derniers jours (glissant)
MensuelLimite sur fenêtre glissante de 30j. 30 derniers jours (glissant)

Laissez un champ vide pour n'appliquer aucun plafond pour cette fenêtre. Lorsqu'un quota est atteint, l'API retourne 401 avec Rate limit exceeded for the API key: et le nom du quota dans le message :

{ "error": "Rate limit exceeded for the API key: quota total" }

Les compteurs de quota sont agrégés à partir des journaux de requêtes et mis en cache jusqu'à 24 heures. L'application est précise dans cette fenêtre, pas à la requête exacte.

Les quotas par clé sont distincts des limites de débit au niveau du plan (plafonds par seconde et par minute s'appliquant à l'ensemble du compte). Les deux retournent 401, avec un message qui nomme la limite atteinte. Voir Gestion des erreurs pour les détails.

Expiration

Définissez une date d'expiration sur les clés utilisées dans les scripts, pipelines CI ou intégrations partenaires. Une fois la date dépassée, l'API retourne :

{ "error": "Expired API Key" }

Code de statut HTTP 401. Créez et déployez une clé de remplacement avant la date d'expiration pour éviter toute interruption.

Journaux de requêtes

Chaque requête effectuée avec une clé est enregistrée sous API → Journal des requêtes dans le tableau de bord, où vous pouvez filtrer par Clé API. Chaque entrée indique :

ChampDescription
Point d'accèsMéthode HTTP et chemin
StatutCode de statut de la réponse
DuréeTemps jusqu'au premier octet (ms)
IPAdresse IP de l'appelant
CréditsCrédits facturés pour cette requête

Utilisez les journaux pour auditer l'activité par clé, déboguer les erreurs inattendues ou identifier le trafic provenant de clés compromises.

Désactivation, archivage ou suppression

ActionEffet
DésactiverModifiez la clé et passez Actif sur Non. La clé est bloquée immédiatement et reste dans la liste. Réactivez-la pour l'utiliser à nouveau.
ArchiverDepuis le menu de la ligne. La clé est bloquée et masquée de la liste. Archivées permet de la revoir. Restaurer la remet dans la liste, toujours inactive. L'alias reste réservé. L'historique des requêtes est conservé.
SupprimerDepuis la fenêtre de modification. Supprime définitivement la clé et sa configuration. Possible uniquement si la clé n'a jamais été utilisée.

Archivez une clé déjà utilisée lorsqu'elle doit quitter la liste. Désactivez-la si vous comptez la réactiver bientôt. Une clé qui a un historique de requêtes ne peut pas être supprimée. L'historique est conservé pour la facturation et l'audit.

Rotation d'une clé

Créer la clé de remplacement

Accédez à API → Clés API dans votre tableau de bord, cliquez sur Nouvelle clé API, et donnez-lui la même catégorie et les mêmes limites de requêtes sous un nouveau nom.

Déployer la nouvelle clé

Mettez à jour la variable d'environnement dans chaque système qui utilise l'ancienne clé et redéployez.

Désactiver l'ancienne clé

Passez l'ancienne clé en inactive, ou archivez-la pour la retirer de la liste. Cela bloque les requêtes restantes sans supprimer son historique.

Référence des erreurs

ErreurStatutCause
Invalid API Key401Clé introuvable ou malformée
Inactive API Key401Clé désactivée
Expired API Key401La clé a dépassé sa date d'expiration
Rate limit exceeded for the API key: quota …401Quota glissant par clé atteint
Rate limit exceeded: You've exceeded the … rate limit on your subscription401Plafond par seconde ou par minute au niveau du plan
IP temporarily blocked403Trop de tentatives d'authentification échouées depuis la même IP

Voir aussi : Bonnes pratiques pour les recommandations de sécurité et Glossaire pour les définitions des termes.

Sur cette page