Créer une application cliente

✓ EnergieID pour les entreprises

Vous développez une application dans laquelle les utilisateurs se connectent avec leur compte EnergieID et donnent à votre application l'accès à leurs données ? Vous enregistrez alors une application cliente OAuth. Votre application n'obtient que l'accès auquel l'utilisateur consent.

Vous avez seulement besoin d'accéder à vos propres données ou à un seul Workspace ? Une clé API est alors plus simple. Lisez Authentification et clés API pour choisir la bonne méthode. Une vue d'ensemble de l'API Web est disponible dans la documentation des API.

Enregistrer votre application

Si vous souhaitez utiliser l'API Web d'EnergieID ou distribuer votre webhook entrant comme application, enregistrez d'abord votre application. Pour cela, envoyez-nous un e-mail avec les informations suivantes :

nom de l'application ;
une icône pour l'application ;
URL de la page d'accueil de l'application ;
une courte description de l'application ;
un lien vers la politique de confidentialité de l'application ;
une liste d'URL de redirection ;
une liste des scopes nécessaires.

Après l'enregistrement, vous recevez un client ID et un client secret.

Suivre le flux OAuth 2.0

L'API Web d'EnergieID utilise le protocole OAuth 2.0 pour l'authentification et l'autorisation. Toutes les applications clientes suivent le même schéma de base en quatre étapes :

Obtenez des identifiants OAuth 2.0.

Enregistrez votre application pour obtenir un client ID et un client secret.
Obtenez un access token auprès de l'EnergieID Authorization Server.

Avant que votre application puisse accéder à des données privées via l'API Web, elle doit obtenir un access token. Le paramètre scope détermine à quels objets et à quelles actions l'access token donne accès.

Demandez d'abord un code d'autorisation. Appelez GET https://identity.energyid.eu/connect/authorize avec les paramètres suivants :
- client_id - obtenu lors de l'enregistrement de votre application
- scope - les autorisations demandées, séparées par des espaces
- response_type - doit valoir code
- redirect_uri - l'URL de callback qui reçoit le code d'autorisation
- state - chaîne unique renvoyée à la fin du processus (facultatif)
- ui_locales - la langue d'affichage souhaitée pour l'écran de connexion et de consentement, par exemple fr-BE ou en-GB (facultatif)
L'utilisateur se connecte avec son compte EnergieID, puis indique s'il accorde les autorisations demandées. S'il accepte, l'Authorization Server envoie un code d'autorisation avec les scopes accordés à votre URL de redirection. S'il refuse, vous recevez une erreur.

Échangez le code d'autorisation contre un access token en appelant POST https://identity.energyid.eu/connect/token avec :
- client_id - obtenu lors de l'enregistrement de votre application
- client_secret - obtenu lors de l'enregistrement de votre application
- grant_type - doit valoir authorization_code
- code - le code d'autorisation de l'étape précédente
- redirect_uri - la même URL de redirection que dans l'appel authorize
Envoyez l'access token à un endpoint de l'API.

Incluez votre access token dans les en-têtes de chaque requête vers l'API Web :
```
Authorization: bearer {AccessToken}
```
Renouvelez l'access token si nécessaire.

Les access tokens ont une durée de vie limitée. Avec un refresh token, votre application demande un nouvel access token sans que l'utilisateur doive se reconnecter. Appelez POST https://identity.energyid.eu/connect/token avec :
- client_id - obtenu lors de l'enregistrement de votre application
- client_secret - obtenu lors de l'enregistrement de votre application
- grant_type - doit valoir refresh_token
- refresh_token - le refresh token reçu avec l'access token

Demander les bons scopes

Ne demandez que les scopes dont votre application a réellement besoin. Les utilisateurs consentent plus facilement lorsqu'ils comprennent pourquoi votre application demande un certain accès.

La plupart des applications pour utilisateurs individuels n'ont besoin que de profile:read et records:read, ou de records:write si elles doivent modifier des données.
Les applications qui travaillent avec des Workspaces demandent workspaces:read ou workspaces:write.
Ajoutez offline_access si votre application a besoin d'un refresh token.

La liste complète des scopes figure dans la documentation des API.

FAQ

Dois-je enregistrer une application si j'utilise seulement une clé API ?

Non. L'enregistrement n'est nécessaire que pour les applications clientes OAuth. Vous créez vous-même une clé API personnelle ou de Workspace dans EnergieID. Lisez Authentification et clés API.

Pourquoi est-ce que je ne reçois pas de refresh token ?

Vous ne recevez un refresh token que si vous incluez le scope offline_access dans l'appel authorize.