Authenticatie en API-sleutels

Je kunt op drie manieren authenticeren bij de EnergieID Web API. Welke methode je kiest, hangt af van wie de integratie beheert en namens wie ze gegevens opvraagt. Met de juiste keuze krijgt je integratie precies de toegang die ze nodig heeft en blijft ze ook op lange termijn beheersbaar.

Een overzicht van de Web API, de scopes en de objectmodellen vind je in de API-documentatie. Alle endpoints staan in de API-referentiedocumentatie (in het Engels).

Kies de juiste methode

OAuth 2.0 voor client-apps

Gebruik OAuth wanneer je applicatie handelt namens gebruikers die zelf aanmelden met hun EnergieID-account en je app toestemming geven. Typische toepassingen:

• web- of mobiele apps waarin gebruikers zelf aanmelden;
• apps voor meerdere klanten, met toestemming per gebruiker;
• toepassingen waarin de gebruiker zelf toegang verleent en weer intrekt.

Lees Een client-app aanmaken om je app te registreren en de OAuth-flow te doorlopen.

Persoonlijke API-sleutels

Gebruik een persoonlijke API-sleutel voor je eigen scripts, prototypes en kleine automatiseringen. De sleutel hoort bij jouw account en geeft toegang tot je profiel en je dossiers. Typische toepassingen:

• je eigen gegevens exporteren;
• command-line tools voor één gebruiker;
• tijdelijke scripts.

Workspace API-sleutels

Gebruik een Workspace API-sleutel voor backend-integraties die eigendom zijn van een organisatie of energiegemeenschap. De sleutel hoort bij de Workspace en niet bij een persoon, dus de integratie blijft werken wanneer de maker de organisatie verlaat. Typische toepassingen:

• synchronisatie met een datawarehouse;
• geplande rapportering over de Workspace;
• server-integraties die niet van één persoon mogen afhangen.

Workspace API-sleutels zijn beschikbaar vanaf het Standard-abonnement. Hoe je ze aanmaakt, roteert en verwijdert, lees je in API-sleutels voor Workspaces.

Bouw je een integratie voor een organisatie die in productie draait? Kies dan voor een Workspace API-sleutel in plaats van een persoonlijke API-sleutel.

Een persoonlijke API-sleutel aanmaken

Een persoonlijke API-sleutel maak je aan in je accountinstellingen:

• Open je gebruikersmenu en klik op Instellingen.
• Ga naar Ontwikkelaarsinstellingen.
• Klik bij API-sleutels op Sleutel genereren.
• Kies Lezen of Lezen & schrijven.
• Klik op Aanmaken.

Op dezelfde plek verwijder je een sleutel die je niet meer gebruikt.

Let op: een persoonlijke API-sleutel geeft toegang tot je volledige account. Bewaar de sleutel veilig en verwijder hem meteen als hij openbaar wordt.

Scopes en toegangsniveaus

Persoonlijke API-sleutels

Een persoonlijke API-sleutel krijgt scopes voor je profiel en je dossiers. Je keuze bij het aanmaken bepaalt of de sleutel ook mag schrijven.

Workspace API-sleutels

Een Workspace API-sleutel krijgt scopes voor de Workspace en voor dossiers. Het toegangsniveau dat je bij het aanmaken kiest, bepaalt de scopes en de Workspace-rol van de sleutel.

• Lezer (workspaces:read, records:read): alleen-leestoegang tot alle dossiers binnen de Workspace.
• Bijdrager (workspaces:write, records:write): meterstanden toevoegen en gebeurtenissen registreren in alle dossiers binnen de Workspace, verder alleen-leestoegang.
• Bewerker (workspaces:write, records:write): alle dossiers binnen de Workspace bewerken, zonder toegangsrechten te beheren of Workspace-instellingen te wijzigen.

De sleutel geeft toegang tot de Workspace-endpoints van die ene Workspace, en tot de dossier-endpoints voor interne dossiers, dus dossiers waarvan de Workspace eigenaar is. Externe dossiers bereik je alleen via de Workspace-endpoints.

OAuth-apps

Een OAuth-app vraagt zelf de scopes aan die ze nodig heeft, ook Workspace-scopes. De gebruiker ziet die scopes wanneer hij toestemming geeft. Het volledige overzicht van de scopes staat in de API-documentatie.

Je sleutel meesturen in een API-verzoek

Stuur je API-sleutel mee in de Authorization-header, voorafgegaan door het woord apikey. Dat geldt voor persoonlijke en Workspace API-sleutels.

Authorization: apikey JOUW_API_SLEUTEL

Let op: gebruik voor een API-sleutel niet het formaat Bearer. Dat formaat is voorbehouden aan OAuth-access tokens (Authorization: bearer {AccessToken}). Een API-sleutel die je als bearer token meestuurt, wordt geweigerd met 401 Unauthorized.

Voorbeeld met een Workspace API-sleutel: de dossiers van een Workspace opvragen. Het Workspace-ID vind je in de adresbalk wanneer je de Workspace opent in de app: https://app.energyid.eu/w/<workspace-id>/....

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

Voorbeeld met een persoonlijke API-sleutel: je eigen dossiers opvragen. Met me verwijs je naar je eigen account, dus je hebt geen gebruikers-ID nodig.

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

Welke endpoints er nog zijn en welke parameters ze aanvaarden, lees je in de API-referentiedocumentatie.

Veelgestelde vragen

Welke methode kies ik voor een backend-integratie die gegevens van één Workspace synchroniseert?

Gebruik een Workspace API-sleutel. Die hoort bij de Workspace, blijft werken wanneer de maker vertrekt en geeft alleen toegang tot die ene Workspace.

Mag ik een persoonlijke API-sleutel gebruiken voor een integratie van mijn team?

Dat raden we af. Een persoonlijke API-sleutel hangt aan één gebruikersaccount en geeft toegang tot dat volledige account. Dat maakt hem moeilijk te beheren wanneer meerdere mensen verantwoordelijk zijn voor de integratie.

Mijn verzoek met een API-sleutel geeft 401 of 403. Wat loopt er mis?

Bij 401 Unauthorized wordt de sleutel niet herkend. Controleer of de header begint met apikey en niet met Bearer, en of de sleutel niet verwijderd is. Bij 403 Forbidden wordt de sleutel wel herkend, maar heeft hij onvoldoende rechten voor die actie, bijvoorbeeld een sleutel met toegangsniveau Lezer die gegevens probeert te wijzigen.

Heb ik OAuth nog nodig als ik API-sleutels gebruik?

Ja, voor apps waarin gebruikers zelf aanmelden en je app toestemming geven. Voor die apps blijft OAuth de juiste methode.