Clés API pour les workspaces

Les clés API vous permettent de connecter des systèmes externes, des outils de reporting ou des pipelines d'automatisation directement à votre workspace EnergieID. Vous échangez ainsi des données de manière sécurisée et automatisée avec vos propres serveurs ou logiciels.

Consultez notre documentation API générale pour en savoir plus sur l'utilisation de votre clé API dans votre intégration backend.

Pourquoi utiliser des clés API ?

Ces clés API sont idéales pour des intégrations backend fiables et durables au sein de votre organisation. Comme la clé est liée au workspace et non à une personne, elle continue de fonctionner même lorsque son créateur quitte l'organisation.

Chaque clé dispose de son propre niveau d'accès, correspondant aux rôles du workspace :

• Lecteur : accès en lecture uniquement.
• Contributeur : accès en écriture avec des permissions de type contributor.
• Éditeur : accès en écriture avec des permissions de type editor.

Remarque : Pour les dossiers internes, l'application distante obtient l'accès aux données détaillées du dossier et des compteurs. Pour les dossiers externes, l'accès est limité aux données disponibles dans le workspace.

Créer une clé API

Les nouvelles clés API ne sont affichées qu'une seule fois, au moment de leur création. Enregistrez immédiatement la valeur de la clé dans un gestionnaire de secrets sécurisé.

• Ouvrez le workspace et allez dans Configuration.
• Ouvrez la fonctionnalité Clés API.
• Cliquez sur Générer une clé.
• Indiquez un nom clair (par exemple le nom du système externe ou de l'intégration).
• Choisissez le niveau d'accès API souhaité (Lecteur, Contributeur ou Éditeur).
• Cliquez sur Créer et copiez la clé immédiatement.

Faire une rotation ou supprimer une clé

Faites une rotation des clés lorsqu'une clé a pu être exposée, lorsque des membres de l'équipe quittent l'organisation, ou dans le cadre régulier de votre gestion périodique de la sécurité. Créez simplement une nouvelle clé pour la même intégration, et ne supprimez l'ancienne clé qu'après avoir mis à jour votre processus distant.

Recommandations de sécurité

• Stockez les clés dans un gestionnaire de secrets, jamais dans le code source.
• Utilisez des clés distinctes par environnement et par intégration.
• Choisissez le niveau d'accès le plus faible dont votre intégration a besoin.
• Faites une rotation des clés régulièrement et après incident.
• Journalisez l'usage des clés dans votre propre backend lorsque c'est possible.

FAQ

Que se passe-t-il avec la clé API lorsque son créateur quitte l'organisation ?

La clé continue de fonctionner normalement. Comme ces clés API sont liées au workspace et non à un utilisateur individuel, vos intégrations et systèmes backend continuent de fonctionner sans interruption.

Puis-je utiliser la même clé API pour plusieurs workspaces ?

Non, une clé API est créée par workspace. Cela garantit une séparation sécurisée des droits d'accès par projet ou par entité de l'organisation.

Quelle est la différence avec une clé API personnelle ?

Ces clés sont destinées aux processus automatisés en arrière-plan et aux intégrations serveur au niveau du workspace. Les clés API personnelles sont liées à un compte utilisateur individuel et ne donnent accès qu'à vos propres dossiers personnels, indépendamment des dossiers du workspace.

Pourquoi ne puis-je plus voir la valeur complète de la clé dans la liste ?

Pour des raisons de sécurité, EnergieID n'affiche la valeur secrète de la clé qu'une seule fois, au moment de sa création. Ensuite, la clé n'est plus affichée pour des raisons de sécurité.

Quelle est la différence entre les dossiers workspace internes et externes pour l'accès API ?

Les dossiers internes offrent un accès plus large, à la fois via les endpoints généraux du workspace et via des endpoints spécifiques au dossier. Les dossiers externes sont plus limités et ne peuvent être consultés que via les endpoints du workspace.