Een client-app aanmaken

✓ EnergieID voor bedrijven

Bouw je een applicatie waarin gebruikers aanmelden met hun EnergieID-account en je app toegang geven tot hun gegevens? Dan registreer je een OAuth-client-app. Je app krijgt dan alleen de toegang waarvoor de gebruiker zelf toestemming geeft.

Heb je alleen toegang nodig tot je eigen gegevens of tot één Workspace? Dan is een API-sleutel eenvoudiger. Lees Authenticatie en API-sleutels om de juiste methode te kiezen. Een overzicht van de Web API vind je in de API-documentatie.

Je applicatie registreren

Wil je de EnergieID Web API gebruiken of je Inkomende Webhook als app aanbieden, registreer dan eerst je applicatie. Dat doe je door ons een e-mail te sturen met de volgende informatie:

  • naam van de applicatie;
  • een icoon voor de applicatie;
  • URL van de homepage van de applicatie;
  • een korte beschrijving van de applicatie;
  • een link naar het privacybeleid van de applicatie;
  • een lijst van redirect-URL's;
  • een lijst van de benodigde scopes.

Na de registratie ontvang je een client ID en een client secret.

De OAuth 2.0-flow doorlopen

De EnergieID Web API gebruikt het OAuth 2.0-protocol voor authenticatie en autorisatie. Alle client-apps volgen hetzelfde basispatroon in vier stappen:

  1. Verkrijg OAuth 2.0-inloggegevens.

    Registreer je app om een client ID en client secret te verkrijgen.

  2. Vraag een access token aan bij de EnergieID Authorization Server.

    Voordat je applicatie via de Web API toegang krijgt tot private gegevens, moet ze een access token verkrijgen. De parameter scope bepaalt tot welke objecten en acties het access token toegang geeft.

    Vraag eerst een autorisatiecode aan. Roep GET https://identity.energyid.eu/connect/authorize aan met de volgende parameters:

    • client_id - verkregen bij de registratie van je app
    • scope - de gevraagde machtigingen, gescheiden door spaties
    • response_type - moet ingesteld zijn op code
    • redirect_uri - de callback-URL die de autorisatiecode ontvangt
    • state - unieke string die na afloop wordt teruggestuurd (optioneel)
    • ui_locales - de taal waarin het aanmeld- en toestemmingsscherm bij voorkeur wordt getoond, bijvoorbeeld nl-BE of en-GB (optioneel)

    De gebruiker meldt zich aan met zijn EnergieID-account en krijgt daarna de vraag of hij de gevraagde machtigingen wil toekennen. Geeft de gebruiker toestemming, dan stuurt de Authorization Server een autorisatiecode samen met de toegekende scopes naar je redirect-URL. Weigert de gebruiker, dan krijg je een fout terug.

    Wissel de autorisatiecode in voor een access token door POST https://identity.energyid.eu/connect/token aan te roepen met:

    • client_id - verkregen bij de registratie van je app
    • client_secret - verkregen bij de registratie van je app
    • grant_type - moet ingesteld zijn op authorization_code
    • code - de autorisatiecode uit de vorige stap
    • redirect_uri - dezelfde redirect-URL als in de authorize-aanroep

  3. Stuur het access token mee naar een API-endpoint.

    Neem bij elk verzoek aan de Web API je access token op in de headers:

    Authorization: bearer {AccessToken}

  4. Vernieuw het access token indien nodig.

    Access tokens hebben een beperkte levensduur. Met een refresh token vraagt je app een nieuw access token aan zonder dat de gebruiker opnieuw moet aanmelden. Roep POST https://identity.energyid.eu/connect/token aan met:

    • client_id - verkregen bij de registratie van je app
    • client_secret - verkregen bij de registratie van je app
    • grant_type - moet ingesteld zijn op refresh_token
    • refresh_token - het refresh token dat je samen met het access token ontving

De juiste scopes aanvragen

Vraag alleen de scopes aan die je app echt nodig heeft. Gebruikers geven sneller toestemming wanneer ze begrijpen waarom je app een bepaalde toegang vraagt.

  • De meeste apps voor individuele gebruikers hebben genoeg aan profile:read en records:read, of records:write als ze gegevens moeten aanpassen.
  • Apps die met Workspaces werken, vragen workspaces:read of workspaces:write aan.
  • Voeg offline_access toe als je app een refresh token nodig heeft.

Het volledige overzicht van de scopes vind je in de API-documentatie.

Veelgestelde vragen

Moet ik een app registreren als ik alleen een API-sleutel gebruik?

Nee. Registratie is alleen nodig voor OAuth-client-apps. Een persoonlijke of Workspace API-sleutel maak je zelf aan in EnergieID. Lees Authenticatie en API-sleutels.

Waarom krijg ik geen refresh token?

Je ontvangt alleen een refresh token wanneer je de scope offline_access opneemt in de authorize-aanroep.