Une clé API est un mot de passe pour un programme. Quiconque la détient peut faire ce que la clé autorise, depuis n’importe où la clé est acceptée, jusqu’à son expiration. Cette page explique comment limiter les dégâts en cas de fuite d’une clé. La création des clés et l’appel de l’API sont décrits dans Authentification.
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 options cochées :
- Une clé ne va jamais au-delà de ce que le membre qui l’a créée peut faire maintenant : « Elle ne dépasse jamais ce que son propriétaire peut faire maintenant. » Si le membre perd une permission, la clé la perd aussi.
- Une clé ne détient jamais de permissions réservées au propriétaire, ni de permissions des modules d’identité et d’accès (connexion, comptes, clés API). Une clé ne peut donc pas créer ou 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 qui transporte une clé est évaluée uniquement en tant que cette clé ; un cookie de navigateur présent sur 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 typiques :
| 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 sur les appareils | Lecture des appareils, écriture des attributs |
| Un système de tickets qui acquitte les alarmes | Lecture des alarmes, acquittement |
Évitez une clé unique 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 provisionnement SCIM. « Les permissions de module ci-dessus sont celles 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 ex. 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é
Toute clé expire : 90 jours par défaut, 365 jours au maximum (« 90 jours par défaut, un an au maximum. ») Dans API Key Settings :
| Réglage | Défaut | Usage |
|---|---|---|
| Maximum Key Lifetime (days) | 0 (le plafond de 365 jours) | Abaissez-le pour imposer des durées de vie plus courtes. Cela abaisse 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 pouvant être actives simultanément. |
| Per-Key Rate Limit (requests/minute) | 0 (la 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 pour illimité ; la plateforme applique 1 000 par minute. |
4. Définir qui est propriétaire 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 de 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 pour que vous puissiez 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édécesseur et la clé successeur.
- Effectuez la rotation et copiez le nouveau secret (« Clé renouvelée. Copiez le nouveau secret maintenant. »).
- 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 : « Les intégrations utilisant cette clé cesseront immédiatement de fonctionner. Cette action est irréversible. »
- Deactivate suspend une clé que vous pourriez vouloir réactiver ; Activate la relance.
- En cas d’incident, un propriétaire peut révoquer plusieurs clés ou toutes les clés ensemble.
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 des incidents concernant les clés. Ses actions de limitation ou de désactivation d’une clé sont In development. 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 nécessaires.
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 les endroits où elle a été utilisée.