API-sleutels voor je workspace beheren

✓ EnergieID voor bedrijven

Met API-sleutels koppel je externe systemen, rapportagetools of automatiseringspijplijnen rechtstreeks aan je EnergieID-workspace. Zo wissel je veilig en geautomatiseerd gegevens uit met je eigen servers of software.

Beschikbaar vanaf het Standard-abonnement.

Hoe je de sleutel meestuurt in je API-verzoeken en welke scopes hij krijgt, lees je in Authenticatie en API-sleutels. Een overzicht van de Web API vind je in de API-documentatie.

Waarom API-sleutels gebruiken?

API-sleutels zijn ideaal voor betrouwbare en doorlopende backend-integraties binnen je organisatie. Omdat de sleutels zijn gekoppeld aan de workspace en niet aan een individueel persoon, blijven ze gewoon actief, zelfs wanneer de maker de organisatie verlaat.

Elke sleutel heeft een eigen toegangsniveau dat overeenkomt met de workspace-rollen:

  • Lezer: alleen-leestoegang tot alle dossiers binnen de workspace.
  • Bijdrager: kan meterstanden toevoegen en gebeurtenissen registreren in alle dossiers binnen de workspace, maar heeft verder alleen-leestoegang.
  • Bewerker: kan alle dossiers binnen de workspace bewerken, maar kan geen toegangsrechten beheren of workspace-instellingen wijzigen.

Let op: Voor de dossiers van je workspace krijgt de remote app toegang tot gedetailleerde dossier- en metergegevens. Voor externe dossiers is de toegang beperkt tot gegevens die beschikbaar zijn in de workspace, en tellen meetgegevens enkel mee als de eigenaar datatoestemming gaf. Lees Werken met externe dossiers.

De functie in- en uitschakelen

  1. Ga in je workspace naar Configuratie.
  2. Klik bij API-sleutels op Activeren.

Je komt op de configuratiepagina, waar je de sleutels aanmaakt en beheert.

Enkel beheerders van de workspace kunnen de functie in- of uitschakelen.

Uitschakelen: klik in Configuratie op API-sleutels, dan op de drie puntjes rechtsboven, en kies Deactiveren. Je kan de functie later opnieuw activeren.

Een API-sleutel aanmaken

Nieuwe API-sleutels worden slechts één keer getoond op het moment van aanmaken. Bewaar de sleutelwaarde meteen in een veilige secret manager.

  • Open de workspace en ga naar Configuratie.

  • Open de functie API-sleutels.

  • Klik op Sleutel genereren.

  • Geef een duidelijke naam op (bijvoorbeeld de naam van het externe systeem of de integratie).

  • Kies het gewenste API-toegangsniveau (Lezer, Bijdrager of Bewerker).

  • Klik op Aanmaken en kopieer de sleutel onmiddellijk.

De sleutel gebruiken in je integratie

Stuur de sleutel mee in de Authorization-header van elk API-verzoek, voorafgegaan door het woord apikey:

Authorization: apikey JOUW_API_SLEUTEL

Zo vraag je bijvoorbeeld de dossiers van je workspace op. 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"

Meer voorbeelden, het verschil met OAuth en wat je doet bij een foutmelding lees je in Authenticatie en API-sleutels. Alle endpoints staan in de API-referentiedocumentatie.

Roteer of verwijder een sleutel

Roteer sleutels als een sleutel mogelijk is blootgesteld, wanneer teamleden de organisatie verlaten, of als vast onderdeel van je periodieke veiligheidsbeheer. Maak eenvoudig een nieuwe sleutel aan voor dezelfde integratie en verwijder pas na aanpassing van je remote process de oude sleutel.

Veiligheidsaanbevelingen

  • Bewaar sleutels in een secret manager, nooit in broncode.
  • Gebruik aparte sleutels per omgeving en per integratie.
  • Kies het laagste toegangsniveau dat je integratie nodig heeft.
  • Roteer sleutels periodiek en na incidenten.
  • Log sleutelgebruik waar mogelijk in je eigen backend.

Veelgestelde vragen

Wat gebeurt er met de API-sleutel als de maker de organisatie verlaat?

De sleutel blijft gewoon actief. Omdat deze API-sleutels gekoppeld zijn aan de workspace en niet aan een individuele gebruiker, blijven je integraties en back-endsystemen ononderbroken doorwerken.

Kan ik dezelfde API-sleutel voor meerdere workspaces gebruiken?

Nee, een API-sleutel wordt per workspace aangemaakt. Dit zorgt voor een veilige scheiding van toegangsrechten per project of organisatieonderdeel.

Wat is het verschil met een persoonlijke API-sleutel?

workspace-sleutels zijn bedoeld voor automatische achtergrondprocessen en server-integraties op workspace-niveau. Persoonlijke API-sleutels zijn gekoppeld aan een individueel gebruikersaccount en geven uitsluitend toegang tot jouw persoonlijke dossiers, los van de workspace-dossiers. Lees Authenticatie en API-sleutels om de juiste sleutel te kiezen.

Waarom kan ik de volledige sleutelwaarde niet meer zien in de lijst?

Om veiligheidsredenen toont EnergieID de geheime sleutel slechts één keer (bij het aanmaken). Daarna wordt de sleutel om redenen van beveiliging niet meer weergegeven.

Wat is het verschil tussen dossiers en externe dossiers voor API-toegang?

Dossiers van je workspace bieden uitgebreidere toegang via zowel de algemene workspace-endpoints als specifieke record-endpoints. Externe dossiers zijn beperkt en kunnen enkel worden aangesproken via de workspace-endpoints.