Clés API
Comment créer, gérer et utiliser des clés API pour un accès programmatique à l’API REST de 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 une 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 autorisations 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 (surveillance, 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 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 autorisations du compte utilisateur associé. Une clé API créée pour un utilisateur Tenant Admin disposera des privilèges Tenant Admin, tandis qu'une clé pour un System Admin aura un accès à l'échelle du système.
Créer 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 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 pour chaque clé
Dernière connexion: Horodatage de l'authentification la plus récente
Dernière IP de connexion: IP source de la dernière authentification
Expire: Jours restants avant expiration
Créée: Horodatage de génération de la clé
Créer une nouvelle clé API
Cliquez sur + Nouvelle clé API au bas du tableau des clés API
Le formulaire s'ouvre avec deux volets : 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 nommage 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éfinissez une date d'expiration spécifique (recommandé pour la sécurité)
N'expire jamais: Créez une clé permanente (à utiliser avec prudence)
Expire (Lorsque « Définir la date » est sélectionné) Utilisez le sélecteur de date/heure pour définir quand la clé doit expirer. Les périodes d'expiration courantes sont de 30, 60 ou 90 jours.
Configurer les contrôles d'accès
Liste d'autorisation d'IP Restreignez la clé API à des adresses IP spécifiques ou à des plages CIDR. Seules les adresses répertoriées peuvent s'authentifier avec cette clé.
Cliquez sur le + (plus) icône pour ajouter une entrée
Entrez 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 selon vos besoins
Liste de refus d'IP Bloquez des adresses IP ou des plages spécifiques pour empêcher l'utilisation de 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
.PAK(fichier de clé API protégée)
Affichage unique
La clé API complète n'est affichée qu'au moment de la 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, localisez 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 d'IP)
Cliquez sur Soumettre pour enregistrer les modifications
Supprimer une clé API
Dans le tableau des clés API, localisez 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. Toute application ou tout script utilisant la clé supprimée échouera à l'authentification.
Utiliser les 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.
Utiliser des restrictions d'IP Configurez autant que possible des listes d'autorisation IP afin de limiter les endroits où la clé peut être utilisée. Cela réduit considérablement le risque si une clé est compromise.
Définir des dates d'expiration Évitez autant que possible les clés permanentes. Une expiration régulière impose une rotation des clés et limite les fenêtres d'exposition.
Surveiller l'utilisation des clés Examinez régulièrement les champs « Dernière connexion » et « Dernière IP de connexion » pour identifier des schémas d'accès inattendus.
Supprimer les clés inutilisées Supprimez les clés API qui ne sont plus nécessaires afin de minimiser votre surface d'attaque.
Dépannage
L'authentification par clé API échoue
Vérifiez que la clé est correctement incluse dans l'en-tête Authorization sous forme de jeton Bearer. Vérifiez l'absence d'espaces supplémentaires ou de troncature.
Accès refusé avec une clé valide
Vérifiez les listes d'autorisation/refus d'IP. Votre IP source peut ne pas être autorisée, ou peut figurer sur 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 restauré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 points de terminaison
Mis à jour
Ce contenu vous a-t-il été utile ?