Une clé d’API est un mot de passe pour un programme. Quiconque la détient peut faire ce que la clé permet, depuis n’importe où la clé est acceptée, jusqu’à son expiration. Cette page explique comment limiter les dégâts d’une clé divulguée. La création des clés et l’appel de l’API sont décrits dans Authentication.
Les clés se gèrent dans API Keys, dans la partie Developer du menu (Admin ; la rotation nécessite le rôle Owner).
Ce qu’une clé ne peut jamais faire
Ces limites s’appliquent à toutes les clés, quelles que soient les cases cochées :
- Une clé ne va jamais au-delà de ce que le membre qui l’a créée peut faire maintenant : « Elle ne va jamais au-delà de ce que son propriétaire peut faire maintenant. » Si le membre perd une permission, la clé la perd aussi.
- Une clé n’obtient jamais les permissions réservées au propriétaire, ni les permissions des modules d’identité et d’accès (connexion, comptes, clés d’API). Ainsi, une clé ne peut pas créer ni faire tourner des clés, ni modifier les membres.
- La permission d’une clé ne fonctionne que si son module est activé pour votre organisation.
- Une requête accompagnée d’une clé est évaluée uniquement en tant que cette clé ; un cookie de navigateur présent dans la même requête est ignoré.
1. N’accorder que les permissions nécessaires
Dans New API Key, choisissez les Module permissions un module à la fois. Chaque module propose un préréglage Read only. Intégrations типiques :
| Intégration | Permissions |
|---|---|
| Un outil de reporting qui lit les appareils et l’historique | Read only sur les appareils et la télémétrie |
| Un ERP qui écrit des limites dans les appareils | Lecture des appareils, écriture des attributs |
| Un système de tickets qui acquitte les alarmes | Lecture et acquittement des alarmes |
Évitez une seule clé pour tout. Une clé par intégration permet de savoir ce qu’une fuite expose et de révoquer une intégration sans arrêter les autres.
Les portées d’intégration (Read, Write, Admin, SCIM Read, SCIM Write) sont destinées aux points de terminaison machine ayant leur propre contrat, comme le provisioning SCIM. « Les permissions de module ci-dessus sont ce dont la plupart des intégrations ont besoin. »
2. Restreindre la clé à des réseaux
IP allowlist (optional) : « Un sous-réseau par ligne, par exemple 10.0.0.0/8 ou 203.0.113.7/32. » Les appels provenant d’ailleurs sont refusés avec la même réponse qu’une clé inconnue, de sorte qu’un attaquant n’apprend rien.
Votre organisation peut définir une valeur par défaut pour les clés sans liste propre : API Key Settings > Tenant Subnet Allowlist.
3. Faire expirer la clé
Chaque clé expire : 90 jours par défaut, 365 jours au maximum (« 90 jours par défaut, un an au maximum. ». Dans API Key Settings :
| Paramètre | Par défaut | Utilisation |
|---|---|---|
| Maximum Key Lifetime (days) | 0 (plafond de 365 jours) | Réduisez-la pour imposer des durées de vie plus courtes. Elle réduit aussi la valeur par défaut. |
| Require Expiry on Every Key | Désactivé | Les appels API qui créent des clés doivent indiquer une date d’expiration. |
| Max Active Keys | 0 (illimité) | Limite le nombre de clés actives simultanément. |
| Per-Key Rate Limit (requests/minute) | 0 (valeur par défaut de la plateforme : 1 000 par minute) | Limite de requêtes par défaut de chaque clé. L’écran affiche 0 comme illimité ; la plateforme applique 1 000 par minute. |
4. Définir qui possède la clé
Une clé cesse de fonctionner lorsque le membre qui l’a créée quitte l’organisation, sauf si elle est marquée Service key (« Oui : survit à son créateur »). Marquez les clés des intégrations en production comme clés de service, et notez qui est responsable de chacune.
5. Faire tourner les clés régulièrement
Rotate key crée une clé successeur : « Crée une clé successeur qui hérite des portées et de l’environnement de cette clé. Pendant la fenêtre de grâce, les deux clés restent actives afin de basculer sans interruption. » Définissez la Grace window (days) ; 0 révoque immédiatement l’ancienne clé. La carte Rotation history relie la clé précédente et la suivante.
- Effectuez la rotation et copiez le nouveau secret (« Clé renouvelée. Copiez maintenant le nouveau secret. »).
- Placez la nouvelle clé dans l’intégration.
- Vérifiez que Last used et Last used IP de l’ancienne clé ne changent plus.
- Laissez la fenêtre de grâce se terminer, ou révoquez l’ancienne clé.
6. Révoquer immédiatement en cas de doute
- Revoke Key : « Toutes les intégrations utilisant cette clé cesseront immédiatement de fonctionner. Cette action est irréversible. »
- Deactivate arrête une clé que vous pourriez vouloir récupérer ; Activate la réactive.
- En cas d’incident, un propriétaire peut révoquer plusieurs clés ou toutes les clés à la fois.
7. Surveiller les clés
| Signal | Où |
|---|---|
| Last used, Last used IP, Total verifications | La page de la clé |
| Une clé inactive soudainement utilisée depuis une nouvelle adresse | Un événement d’audit (api_key.anomaly.detected) |
| Vérifications échouées | Événements d’audit (api_key.verify.failed) |
| Création, rotation, suppression, modifications de permissions | Le journal d’audit (api_key.created, api_key.rotated, api_key.deleted) |
| Abus | Le pare-feu IA enregistre les incidents concernant les clés et peut limiter ou révoquer une clé. Voir Le pare-feu IA. |
La liste des clés affiche aussi une bannière pour les anciennes clés créées avant les permissions par module : ouvrez chacune et n’accordez que les permissions de module dont elle a besoin.
Stockage des clés
- Conservez les clés dans le coffre à secrets de votre intégration, jamais dans le code source, les URL ou les tickets.
- Utilisez des clés
testpour les systèmes de test, afin qu’elles ne soient pas confondues avec les clés de production. - Si une clé a fuité, révoquez-la d’abord, puis identifiez dans le journal d’audit d’où elle a été utilisée.

