> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/fr/surfaces-dadministration-partagees/api-keys.md). # Clés API ## 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. {% hint style="info" %} **Clés API vs. jetons de session** Les jetons de session sont des identifiants temporaires qui expirent après une période d’inactivité. Les clés API sont conçues pour un accès programmatique de longue durée et restent valides jusqu’à leur expiration ou leur suppression. {% endhint %} ## Création d’une clé API ### Accéder à la gestion des clés API 1. Depuis le menu principal de VergeOS, accédez à **Système > Utilisateurs** 2. Sélectionnez le compte utilisateur qui sera propriétaire de la clé API 3. 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 1. Cliquez sur **+ Nouvelle clé API** en bas du tableau des clés API 2. 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é. 1. Cliquez sur le **+ (plus)** icône pour ajouter une entrée 2. Saisissez une adresse IP (par ex. `192.168.1.100`) ou une plage CIDR (par ex. `192.168.1.0/24`) 3. Cochez la case pour activer l’entrée 4. 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. 1. Cliquez sur le **+ (plus)** icône pour ajouter une entrée 2. Saisissez l’adresse IP ou la plage CIDR à bloquer 3. Cochez la case pour activer l’entrée {% hint style="info" %} **Priorité entre la liste d’autorisation et la liste de refus** Lorsque les deux listes sont configurées, la liste d’autorisation IP est prioritaire. Si une adresse figure dans les deux listes, c’est la liste d’autorisation qui détermine l’accès. {% endhint %} ### Enregistrer et récupérer la clé API 1. Vérifiez l’exactitude de tous les paramètres 2. 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) {% hint style="danger" %} **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. {% endhint %} 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 1. Dans le tableau des clés API, repérez la clé que vous souhaitez modifier 2. Cliquez sur le **Modifier** icône (crayon) à côté du nom de la clé 3. Mettez à jour les paramètres (nom, description, expiration, listes IP) 4. Cliquez sur **Soumettre** pour enregistrer les modifications {% hint style="info" %} **La chaîne de la clé ne peut pas être modifiée** La modification d’une clé API met uniquement à jour ses métadonnées et ses contrôles d’accès. La chaîne de clé elle-même ne peut pas être modifiée. Pour changer la chaîne de clé, vous devez créer une nouvelle clé API et supprimer l’ancienne. {% endhint %} ### Supprimer une clé API 1. Dans le tableau des clés API, repérez la clé que vous souhaitez supprimer 2. Cliquez sur le **Supprimer** icône (corbeille) à côté du nom de la clé 3. Confirmez la suppression {% hint style="warning" %} **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. {% endhint %} ## 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 : ``` Authorization: Bearer ``` ### Exemple de requête API ```bash curl -X GET "https://votre-instance-vergeos/api/v4/system" \ -H "Authorization: Bearer votre-chaîne-de-clé-api-ici" \ -H "Content-Type: application/json" ``` ### 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 : ```bash # Définir la variable d’environnement export VERGEOS_API_KEY="votre-chaîne-de-clé-api" # Utiliser dans la requête API curl -X GET "https://votre-instance-vergeos/api/v4/system" \ -H "Authorization: Bearer ${VERGEOS_API_KEY}" ``` ## 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](/knowledge-base/fr/automation-api/verge-api-guide.md) - Référence complète de l’API et des points de terminaison --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/automate-protect-and-extend/fr/surfaces-dadministration-partagees/api-keys.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.