Clés API¶
Les clés API permettent d'interagir avec l'API Avalon de manière programmatique, sans passer par l'interface web. Elles sont idéales pour les intégrations, scripts d'automatisation ou outils tiers.
Contrairement aux comptes utilisateurs, les clés API sont globales : elles ne sont pas liées à un utilisateur spécifique ni à un tenant. Chaque clé porte ses propres permissions, selon la même structure que les rôles.
Créer une clé API¶
Pour créer une nouvelle clé, cliquez sur le bouton + en haut de la page. Le formulaire comprend :
- Name : Un nom descriptif pour identifier la clé (ex :
monitoring_readonly,ci_deploy). - Expires at : Date d'expiration optionnelle. A cette date, la clé sera automatiquement refusée. Laissez vide pour une clé sans expiration.
Permissions¶
Les permissions sont identiques à celles des rôles, à l'exception de WebSSH qui n'est pas disponible pour les clés API.
Vous pouvez activer All permissions pour un accès complet, ou configurer chaque section individuellement. Consultez la page Gestion des rôles pour le détail de chaque permission.
Sauvegardez votre clé
Le token est affiché une seule fois après la création. Copiez-le et stockez-le dans un endroit sûr. Il est impossible de le récupérer ultérieurement.
Le token généré est au format : ak_avalon_<token>
Utilisation¶
Pour authentifier une requête API avec une clé, ajoutez le header suivant :
X-API-Key: ak_avalon_<votre_token>
Coexistence avec l'authentification JWT
Si une requête contient à la fois un header Authorization: Bearer <JWT> et un header X-API-Key, la clé API prend la priorité.
Cycle de vie d'une clé¶
Statuts¶
| Statut | Condition | Indicateur |
|---|---|---|
| Active | Non révoquée ET (pas de date d'expiration OU date d'expiration dans le futur) | Vert |
| Revoked | Clé révoquée manuellement | Rouge |
| Expired | Date d'expiration dépassée | Gris |
Révoquer une clé¶
La révocation désactive immédiatement une clé sans la supprimer de la base de données. Toutes les requêtes utilisant cette clé seront refusées.
Pour révoquer une clé, cliquez sur le bouton de révocation associé à la clé dans la liste.
Tip
La révocation est préférable à la suppression : elle conserve un historique d'audit tout en bloquant immédiatement l'accès.
Supprimer une clé¶
La suppression retire définitivement la clé de la base de données. Seules les clés révoquées ou expirées peuvent être supprimées.
Bonnes pratiques¶
- Principe du moindre privilège : N'accordez que les permissions strictement nécessaires à l'usage prévu de la clé.
- Rotation régulière : Utilisez une date d'expiration et renouvelez vos clés périodiquement.
- Une clé par usage : Créez des clés distinctes pour chaque intégration ou script afin de pouvoir les révoquer indépendamment.
- Ne partagez jamais un token : Chaque clé doit être connue uniquement du système qui l'utilise.