Clés API
Comment créer, gérer et utiliser des clés API pour l’accès programmatique à l’API REST VergeOS, y compris l’authentification, les contrôles d’accès IP, les paramètres d’expiration et les bonnes pratiques de sécurité.
Vue d’ensemble
Les clés API fournissent l’authentification pour l’accès programmatique à l’API REST VergeOS et aux services intégrés. Chaque clé API est associée à un compte utilisateur spécifique et hérite des permissions et des niveaux d’accès de cet utilisateur. Cela permet aux applications, scripts et outils tiers d’interagir avec VergeOS sans nécessiter de sessions de connexion interactives.
Utilisations courantes des clés API :
Authentification à l’API REST pour l’automatisation et l’intégration
Accès au routeur d’IA compatible OpenAI
Intégration d’outils tiers (supervision, orchestration, outils IaC)
Authentification des pipelines CI/CD
Comprendre l’authentification par clé API
Dans VergeOS, les clés API fonctionnent comme des jetons Bearer dans l’en-tête HTTP Authorization. Contrairement aux jetons de session générés lors de la connexion à l’interface utilisateur (qui expirent après une période d’inactivité), les clés API restent valides jusqu’à leur date d’expiration configurée ou leur suppression manuelle.
Chaque clé API hérite de toutes les permissions du compte utilisateur associé. Une clé API créée pour un utilisateur Administrateur de locataire aura les privilèges d’un Administrateur de locataire, tandis qu’une clé pour un Administrateur système aura un accès à l’échelle du système.
Création d’une clé API
Accéder à la gestion des clés API
Depuis le menu principal de VergeOS, accédez à Système > Utilisateurs
Sélectionnez le compte utilisateur qui sera propriétaire de la clé API
Dans le tableau de bord de l’utilisateur, cliquez sur le Clés API widget pour afficher les clés existantes
La section Clés API affiche un tableau avec :
Nom: Identifiant descriptif de chaque clé
Dernière connexion: Horodatage de la dernière authentification
IP de la dernière connexion: Adresse IP source de la dernière authentification
Expire: Nombre de jours restants avant l’expiration
Créée: Horodatage de génération de la clé
Créer une nouvelle clé API
Cliquez sur + Nouvelle clé API en bas du tableau des clés API
Le formulaire s’ouvre avec deux panneaux : Clé API (gauche) et Accès (droite)
Configurer les paramètres de la clé API
Nom (Obligatoire) Saisissez un identifiant descriptif pour la clé API. Un nom clair facilite le suivi et la gestion des clés.
Description (Facultatif) Ajoutez un contexte supplémentaire sur la finalité de la clé, le demandeur ou les systèmes associés.
Type d’expiration Choisissez comment la période de validité de la clé est gérée :
Définir la date: Définir une date d’expiration précise (recommandé pour la sécurité)
Ne jamais expirer: Créer une clé permanente (à utiliser avec prudence)
Expire (Lorsque « Définir une date » est sélectionné) Utilisez le sélecteur de date/heure pour définir quand la clé doit expirer. Les durées d’expiration courantes sont de 30, 60 ou 90 jours.
Configurer les contrôles d’accès
Liste d’autorisation IP Restreignez la clé API à des adresses IP ou des plages CIDR spécifiques. Seules les adresses répertoriées peuvent s’authentifier avec cette clé.
Cliquez sur le + (plus) icône pour ajouter une entrée
Saisissez une adresse IP (par ex.
192.168.1.100) ou une plage CIDR (par ex.192.168.1.0/24)Cochez la case pour activer l’entrée
Ajoutez d’autres entrées si nécessaire
Liste de refus IP Bloquez des adresses IP ou des plages spécifiques pour cette clé tout en autorisant toutes les autres.
Cliquez sur le + (plus) icône pour ajouter une entrée
Saisissez l’adresse IP ou la plage CIDR à bloquer
Cochez la case pour activer l’entrée
Enregistrer et récupérer la clé API
Vérifiez l’exactitude de tous les paramètres
Cliquez sur Soumettre pour générer la clé API
Une fenêtre contextuelle affiche la clé API générée avec deux options :
Copier: Cliquez pour copier la chaîne complète de la clé dans votre presse-papiers
Enregistrer: Cliquez pour télécharger la clé sous forme de fichier
.PAK(clé API protégée)
Affichage unique
La clé API complète n’est affichée qu’au moment de sa création. Une fois cette fenêtre contextuelle fermée, la clé complète ne peut plus être récupérée. Si vous perdez la clé, vous devez la supprimer et en créer une nouvelle.
Après avoir sécurisé la clé, fermez la fenêtre contextuelle. La nouvelle clé API apparaît dans le tableau des clés API.
Gestion des clés API existantes
Modifier une clé API
Dans le tableau des clés API, repérez la clé que vous souhaitez modifier
Cliquez sur le Modifier icône (crayon) à côté du nom de la clé
Mettez à jour les paramètres (nom, description, expiration, listes IP)
Cliquez sur Soumettre pour enregistrer les modifications
Supprimer une clé API
Dans le tableau des clés API, repérez la clé que vous souhaitez supprimer
Cliquez sur le Supprimer icône (corbeille) à côté du nom de la clé
Confirmez la suppression
Révocation immédiate
La suppression d’une clé API révoque immédiatement tout accès. Les applications ou scripts utilisant la clé supprimée échoueront à l’authentification.
Utilisation des clés API
Format d’authentification
Les clés API sont utilisées dans l’en-tête HTTP Authorization sous forme de jetons Bearer :
Exemple de requête API
Stockage dans une variable d’environnement
Pour des raisons de sécurité, chargez les clés API depuis des variables d’environnement plutôt que de les coder en dur :
Considérations de sécurité
Traitez les clés API comme des mots de passe Les clés API fournissent une authentification complète en tant qu’utilisateur associé. Protégez-les avec le même soin que les mots de passe.
Utilisez des restrictions IP Configurez autant que possible des listes d’autorisation IP pour limiter les endroits où la clé peut être utilisée. Cela réduit considérablement le risque en cas de compromission d’une clé.
Définissez des dates d’expiration Évitez les clés permanentes lorsque c’est possible. Une expiration régulière impose une rotation des clés et limite les périodes d’exposition.
Surveillez l’utilisation des clés Examinez régulièrement les champs « Dernière connexion » et « IP de la dernière connexion » pour identifier tout schéma d’accès inattendu.
Supprimez les clés inutilisées Supprimez les clés API qui ne sont plus nécessaires afin de réduire votre surface d’attaque.
Dépannage
L’authentification par clé API échoue
Vérifiez que la clé est incluse correctement dans l’en-tête Authorization sous forme de jeton Bearer. Vérifiez qu’il n’y a pas d’espaces supplémentaires ni de troncature.
Accès refusé avec une clé valide
Vérifiez les listes IP d’autorisation/refus. Votre IP source peut ne pas être autorisée ou figurer dans la liste de refus.
Clé expirée
Vérifiez la colonne « Expire » dans le tableau des clés API. Créez une nouvelle clé si l’ancienne a expiré.
Impossible de récupérer la clé perdue
Les clés API ne peuvent pas être récupérées après la fermeture de la fenêtre contextuelle de création initiale. Supprimez la clé perdue et créez-en une nouvelle.
Ressources associées
Documentation de l’API REST VergeOS - Référence complète de l’API et des points de terminaison
Mis à jour
Ce contenu vous a-t-il été utile ?