Authentification et clés API

✓ EnergieID pour les entreprises

Vous pouvez vous authentifier auprès de l'API Web d'EnergieID de trois manières. La méthode à choisir dépend de qui gère l'intégration et au nom de qui elle demande des données. Avec le bon choix, votre intégration obtient exactement l'accès dont elle a besoin et reste facile à gérer sur le long terme.

Une vue d'ensemble de l'API Web, des scopes et des modèles d'objets est disponible dans la documentation des API. Tous les endpoints figurent dans la documentation de référence de l'API (en anglais).

Choisir la bonne méthode

OAuth 2.0 pour les applications clientes

Utilisez OAuth lorsque votre application agit au nom d'utilisateurs qui se connectent avec leur propre compte EnergieID et donnent leur consentement à votre application. Cas d'usage typiques :

applications web ou mobiles dans lesquelles les utilisateurs se connectent eux-mêmes ;
applications pour plusieurs clients, avec un consentement par utilisateur ;
scénarios dans lesquels l'utilisateur accorde et retire lui-même l'accès.

Lisez Créer une application cliente pour enregistrer votre application et suivre le flux OAuth.

Clés API personnelles

Utilisez une clé API personnelle pour vos propres scripts, prototypes et petites automatisations. La clé est liée à votre compte et donne accès à votre profil et à vos dossiers. Cas d'usage typiques :

exporter vos propres données ;
outils en ligne de commande pour un seul utilisateur ;
scripts temporaires.

Clés API de Workspace

Utilisez une clé API de Workspace pour les intégrations backend qui appartiennent à une organisation ou à une communauté d'énergie. La clé est liée au Workspace et non à une personne : l'intégration continue donc de fonctionner lorsque son créateur quitte l'organisation. Cas d'usage typiques :

synchronisation avec un entrepôt de données ;
rapports planifiés sur le Workspace ;
intégrations serveur qui ne doivent pas dépendre d'une seule personne.

Les clés API de Workspace sont disponibles à partir de l'abonnement Standard. La création, la rotation et la suppression sont expliquées dans Clés API pour les Workspaces.

Vous développez une intégration d'organisation qui tourne en production ? Choisissez une clé API de Workspace plutôt qu'une clé API personnelle.

Créer une clé API personnelle

Vous créez une clé API personnelle dans les paramètres de votre compte :

Ouvrez votre menu utilisateur et cliquez sur Paramètres.
Allez dans Paramètres de développement.
Sous Clés d'API, cliquez sur Générer la clé.
Choisissez Lire ou Lire et écrire.
Cliquez sur Créer.

C'est au même endroit que vous supprimez une clé que vous n'utilisez plus.

Attention : une clé API personnelle donne accès à l'ensemble de votre compte. Conservez la clé en lieu sûr et supprimez-la immédiatement si elle devient publique.

Scopes et niveaux d'accès

Clés API personnelles

Une clé API personnelle reçoit des scopes pour votre profil et vos dossiers. Votre choix lors de la création détermine si la clé peut aussi écrire.

Choix lors de la création	Scopes
Lire	profile:read, records:read
Lire et écrire	profile:write, records:write

Clés API de Workspace

Une clé API de Workspace reçoit des scopes pour le Workspace et pour les dossiers. Le niveau d'accès choisi lors de la création détermine les scopes et le rôle de la clé dans le Workspace.

Lecteur (workspaces:read, records:read): accès en lecture seule à tous les dossiers du Workspace.
Contributeur (workspaces:write, records:write): ajouter des relevés de compteurs et enregistrer des événements dans la chronologie de tous les dossiers du Workspace, sinon accès en lecture seule.
Éditeur (workspaces:write, records:write): modifier tous les dossiers du Workspace, sans gérer les droits d'accès ni modifier les paramètres du Workspace.

La clé donne accès aux endpoints de Workspace de ce seul Workspace, et aux endpoints de dossier pour les dossiers internes, c'est-à-dire les dossiers dont le Workspace est propriétaire. Les dossiers externes ne sont accessibles que via les endpoints de Workspace.

Applications OAuth

Une application OAuth demande elle-même les scopes dont elle a besoin, y compris les scopes de Workspace. L'utilisateur voit ces scopes lorsqu'il donne son consentement. La liste complète des scopes figure dans la documentation des API.

Envoyer votre clé avec une requête API

Envoyez votre clé API dans l'en-tête Authorization, précédée du mot apikey. Cela vaut pour les clés API personnelles comme pour les clés API de Workspace.

Authorization: apikey VOTRE_CLE_API

Attention : n'utilisez pas le format Bearer pour une clé API. Ce format est réservé aux access tokens OAuth (Authorization: bearer {AccessToken}). Une clé API envoyée comme bearer token est refusée avec 401 Unauthorized.

Exemple avec une clé API de Workspace : lister les dossiers d'un Workspace. Vous trouvez l'ID du Workspace dans la barre d'adresse lorsque vous ouvrez le Workspace dans l'application : https://app.energyid.eu/w/<workspace-id>/....

curl "https://api.energyid.eu/api/v1/Workspaces/<workspace-id>/records" \
  -H "Authorization: apikey VOTRE_CLE_API"

Exemple avec une clé API personnelle : lister vos propres dossiers. me désigne votre propre compte, vous n'avez donc pas besoin d'un ID utilisateur.

curl "https://api.energyid.eu/api/v1/Members/me/records" \
  -H "Authorization: apikey VOTRE_CLE_API"

Les autres endpoints et les paramètres qu'ils acceptent sont décrits dans la documentation de référence de l'API.

FAQ

Quelle méthode choisir pour une intégration backend qui synchronise les données d'un seul Workspace ?

Utilisez une clé API de Workspace. Elle est liée au Workspace, continue de fonctionner lorsque son créateur part et ne donne accès qu'à ce seul Workspace.

Puis-je utiliser une clé API personnelle pour l'intégration de mon équipe ?

Nous le déconseillons. Une clé API personnelle est liée à un seul compte utilisateur et donne accès à l'ensemble de ce compte. Elle est donc difficile à gérer lorsque plusieurs personnes sont responsables de l'intégration.

Ma requête avec une clé API renvoie 401 ou 403. Que se passe-t-il ?

Avec 401 Unauthorized, la clé n'est pas reconnue. Vérifiez que l'en-tête commence par apikey et non par Bearer, et que la clé n'a pas été supprimée. Avec 403 Forbidden, la clé est reconnue mais n'a pas les droits nécessaires pour cette action, par exemple une clé avec le niveau d'accès Lecteur qui tente de modifier des données.

Ai-je encore besoin d'OAuth si j'utilise déjà des clés API ?

Oui, pour les applications dans lesquelles les utilisateurs se connectent eux-mêmes et donnent leur consentement. Pour ces applications, OAuth reste la bonne méthode.