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 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é via les journaux de requêtes.
Pour savoir comment inclure une clé dans une requête, consultez l'Introduction.
Créer une clé
Remplir les champs
Donnez à la clé un alias (étiquette unique pour votre référence), choisissez une catégorie et configurez éventuellement des quotas et une date d'expiration.
Copier le secret
Après l'enregistrement, le secret est affiché une seule fois. Copiez-le immédiatement et stockez-le dans une variable d'environnement. Il ne peut pas être récupéré à nouveau.
Champs de la clé
| Champ | Description |
|---|---|
| Alias | Étiquette unique par compte. Apparaît dans les journaux et les filtres du tableau de bord. |
| Catégorie | Étiquette d'organisation (voir Catégories). N'a aucun effet sur le comportement de l'API. |
| Active | Active ou désactive la clé. Les clés inactives sont rejetées immédiatement avec 401 Inactive API Key. |
| Expire | Date optionnelle après laquelle la clé cesse de fonctionner. Laissez vide pour ne pas avoir d'expiration. |
| Quotas de requêtes | Plafonds 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égorie | Utilisation typique |
|---|---|
production | Trafic en direct, systèmes orientés client |
development | Développement local et tests |
staging | Environnements de pré-production et CI |
| Personnalisée | Toute é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) :
| Quota | Fenêtre |
|---|---|
| Total | Depuis toujours : la clé est bloquée définitivement une fois atteint |
| Quotidien | Dernières 24 heures (glissant, pas de minuit à minuit) |
| Hebdomadaire | 7 derniers jours (glissant) |
| Mensuel | 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 Rate Limit Exceeded avec le nom du quota dans le message :
{ "error": "Rate limit exceeded: quota total" }{ "error": "Rate limit exceeded: quota daily" }{ "error": "Rate limit exceeded: quota weekly" }{ "error": "Rate limit exceeded: quota monthly" }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 limites de plan retournent 429 Too Many Requests. 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 Clés API → Journaux dans le tableau de bord. Chaque entrée indique :
| Champ | Description |
|---|---|
| Endpoint | Méthode HTTP et chemin |
| Statut | Code de statut de la réponse |
| Durée | Temps jusqu'au premier octet (ms) |
| IP | Adresse IP de l'appelant |
| Crédits | Cré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 vs. suppression
| Action | Effet |
|---|---|
| Désactiver | La clé est bloquée immédiatement. L'historique d'utilisation et les paramètres sont conservés. Peut être réactivée. |
| Supprimer | Supprime définitivement la clé et sa configuration. Possible uniquement si la clé n'a jamais été utilisée. |
Préférez la désactivation à la suppression. Si une clé a un historique de requêtes, elle ne peut pas être supprimée. L'historique est conservé à des fins de facturation et d'audit.
Rotation d'une clé
Créer la clé de remplacement
Accédez à tableau de bord → Clés API → Nouvelle et créez une nouvelle clé avec les mêmes paramètres de catégorie et de quota. Donnez-lui un nouvel alias pour la distinguer.
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 dans le tableau de bord. Cela bloque les requêtes restantes sans supprimer son historique.
Référence des erreurs
| Erreur | Statut | Cause |
|---|---|---|
Invalid API Key | 401 | Clé introuvable ou malformée |
Inactive API Key | 401 | Clé désactivée |
Expired API Key | 401 | La clé a dépassé sa date d'expiration |
Rate limit exceeded: quota … | 401 | Quota glissant par clé atteint |
exceeded the … rate limit on your subscription | 429 | Plafond par seconde ou par minute au niveau du plan |
IP temporarily blocked | 403 | Trop 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.