API-sleutel aanmaken

Een API-sleutel geeft je eigen software toegang tot de REST API van ModbusCloud. De sleutel hoort bij de organisatie en niet bij één klant. Met de sleutel leest je software dus de gateways van al je klanten, binnen de rechten van de sleutel. Welke gegevens de API en webhooks leveren, staat in REST API en webhooks.

Wat je nodig hebt

• De rol Eigenaar of Beheerder in je organisatie. Bij de andere rollen staat API-sleutels niet onder Instellingen. Wie wat mag, staat in Teamleden en rollen.
• Een veilige plek voor de sleutel, zoals de instellingen van de software die hem gebruikt of een wachtwoordkluis.

Rechten kiezen

Een sleutel mag alleen wat zijn rechten toestaan. Vraagt je software iets zonder het juiste recht, dan antwoordt de API met status 403 en de code insufficient_scope.

De tabel laat de rechten zien die de endpoints in de API-referentie vragen. In de lijst met sleutels staat elk recht als scope.

Vink alleen aan wat je software gebruikt. Met alleen deze leesrechten verandert een sleutel niets in je organisatie. De andere rechten in het venster heb je voor de endpoints in de API-referentie niet nodig.

Rechten pas je achteraf niet aan. Heeft je software een ander recht nodig, maak dan een nieuwe sleutel en trek de oude in. Wil je alarmen meteen ontvangen in plaats van ze steeds op te vragen, volg dan Webhook instellen.

Sleutel aanmaken

Maak per koppeling een eigen sleutel. Dan trek je er één in zonder de andere koppelingen te raken. Elke sleutel heeft ook een eigen grens van 100 verzoeken per minuut.

1. Instellingen openen

   Ga naar Instellingen > API-sleutels.

2. Venster openen

   Klik rechtsboven op Nieuwe sleutel.

3. Naam invullen

   Vul bij Naam een naam in waaraan je de koppeling herkent, bijvoorbeeld Energierapportage kantoor.

4. Rechten aanvinken

   Vink onder Rechten de rechten aan die de koppeling nodig heeft. Aanmaken werkt pas met een naam en minstens één recht.

5. Sleutel aanmaken

   Klik op Aanmaken. Het venster toont de sleutel met de melding Kopieer deze sleutel nu. Je kunt hem niet meer opvragen.

6. Sleutel kopiëren

   Klik rechts naast de sleutel op het icoon met de twee vierkantjes. Het portaal meldt Gekopieerd.

7. Sleutel bewaren

   Plak de sleutel in de software die hem gebruikt, of in een wachtwoordkluis.

8. Venster sluiten

   Klik op Sluiten. De sleutel staat nu in de lijst met de status Actief.

De sleutel bestaat uit mlk_ en 64 tekens daarachter. ModbusCloud bewaart alleen een hash van de sleutel en de eerste 12 tekens. Die 12 tekens staan bij Prefix in de lijst. Ben je de sleutel kwijt, maak dan een nieuwe aan en trek de oude in.

Sleutel testen

Het blok Test verbinding laat zien of een sleutel werkt en wat hij mag. Het staat op dezelfde pagina, onder de lijst met sleutels.

1. Sleutel plakken

   Plak de sleutel in het veld onder Test verbinding.

2. Verbinding testen

   Klik op Testen. Klopt de sleutel, dan heet het blok nu API Explorer. Erin staat Sleutel gevalideerd met de naam, de organisatie en de rechten van de sleutel.

3. Categorie openen

   Klik in het blok API Explorer op een categorie, bijvoorbeeld Registers.

4. Endpoint proberen

   Klik bij een endpoint met GET op Probeer dit endpoint. Het portaal stuurt het verzoek met de sleutel naar de API en toont het antwoord eronder.

Is de sleutel onbekend, ingetrokken of niet helemaal gekopieerd, dan staat er Verbinding mislukt met de HTTP-status, bijvoorbeeld HTTP 401. Categorieën waarvoor de sleutel geen recht heeft, staan onder Niet beschikbaar met deze sleutel. Staat er bij een endpoint Geen gateway beschikbaar, dan mist de sleutel Gateways lezen of heeft je organisatie nog geen gateway.

Buiten het portaal test je de sleutel met het endpoint /introspect. Dat geeft de naam, de rechten en de organisatie van de sleutel terug en werkt met elke geldige sleutel.

curl https://api.modbuscloud.com/v1/introspect \
  -H "Authorization: Bearer mlk_..."

In het demo-account maak je geen sleutels aan. Probeer de API daar met de openbare sandboxsleutel uit de quickstart van de API-referentie.

Registers schrijven toestaan

Het recht Registers schrijven staat grijs met de toevoeging op aanvraag, zolang aansturen op geen enkele gateway van je organisatie aanstaat. Aansturen vraag je per gateway aan, zoals beschreven in Registers aansturen.

Staat aansturen op minstens één gateway aan, dan vink je Registers schrijven aan bij een nieuwe sleutel. Schrijven via de API werkt alleen op de gateways waar aansturen aanstaat. Op een andere gateway antwoordt de API met status 403 en de code write_not_enabled, welke rechten de sleutel ook heeft.

Sleutel intrekken

Een ingetrokken sleutel werkt direct niet meer. Het volgende verzoek met die sleutel krijgt status 401 met de code api_key_revoked.

Bij Laatst gebruikt staat de datum van het laatste verzoek met een sleutel, ook als dat een test in het portaal was. Zo zie je welke sleutels nog in gebruik zijn. Bij een sleutel die nooit een verzoek deed, staat Nooit.

1. Instellingen openen

   Ga naar Instellingen > API-sleutels.

2. Sleutel zoeken

   Zoek de sleutel in de lijst op Naam, of op de eerste tekens bij Prefix.

3. Sleutel intrekken

   Klik rechts in de rij op het rode prullenbakje. Het portaal meldt API-sleutel ingetrokken en de status wordt Ingetrokken.