> 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/run-the-platform/fr/administration-systeme/api-keys.md). # Clés API ## 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. {% hint style="info" %} **Clés API vs. jetons de session** Les jetons de session sont des identifiants temporaires qui expirent après inactivité. Les clés API sont conçues pour un accès programmatique de longue durée et restent valides jusqu'à expiration ou suppression. {% endhint %} ## Créer 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 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 1. Cliquez sur **+ Nouvelle clé API** au bas du tableau des clés API 2. 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é. 1. Cliquez sur le **+ (plus)** icône pour ajouter une entrée 2. Entrez 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 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. 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 liste d'autorisation et liste de refus** Lorsque les deux listes sont configurées, la liste d'autorisation d'IP est prioritaire. Si une adresse apparaît dans les deux listes, la liste d'autorisation 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 `.PAK` (fichier de clé API protégée) {% hint style="danger" %} **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. {% 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, localisez 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 d'IP) 4. Cliquez sur **Soumettre** pour enregistrer les modifications {% hint style="info" %} **La chaîne de 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, localisez 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. Toute application ou tout script utilisant la clé supprimée échouera à l'authentification. {% endhint %} ## 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 : ``` Authorization: Bearer ``` ### Exemple de requête API ```bash curl -X GET "https://your-vergeos-instance/api/v4/system" \ -H "Authorization: Bearer your-api-key-string-here" \ -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="your-api-key-string" # Utiliser dans la requête API curl -X GET "https://your-vergeos-instance/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. **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](/knowledge-base/fr/automation-api/verge-api-guide.md) - Référence complète de l'API et 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/run-the-platform/fr/administration-systeme/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.