API-Schlüssel erstellen

Ein API-Schlüssel gibt Ihrer eigenen Software Zugriff auf die REST-API von ModbusCloud. Der Schlüssel gehört zur Organisation und nicht zu einem einzelnen Kunden. Ihre Software liest damit die Gateways aller Ihrer Kunden, im Rahmen der Berechtigungen des Schlüssels. Welche Daten die API und Webhooks liefern, steht unter REST-API und Webhooks.

Was Sie brauchen

• Die Rolle Eigentümer oder Administrator in Ihrer Organisation. Bei den anderen Rollen fehlt API-Schlüssel unter Einstellungen. Wer was darf, steht unter Teammitglieder und Rollen.
• Einen sicheren Ort für den Schlüssel, etwa die Einstellungen der Software, die ihn verwendet, oder einen Passwort-Tresor.

Berechtigungen wählen

Ein Schlüssel darf nur das, was seine Berechtigungen erlauben. Fragt Ihre Software etwas ohne die passende Berechtigung an, antwortet die API mit Status 403 und dem Code insufficient_scope.

Die Tabelle zeigt die Berechtigungen, die die Endpoints in der API-Referenz verlangen. In der Schlüsselliste steht jede Berechtigung als Scope.

Aktivieren Sie nur, was Ihre Software verwendet. Mit diesen reinen Leseberechtigungen ändert ein Schlüssel nichts in Ihrer Organisation. Die übrigen Berechtigungen im Fenster brauchen Sie für die Endpoints der API-Referenz nicht.

Berechtigungen passen Sie nachträglich nicht an. Braucht Ihre Software eine andere Berechtigung, erstellen Sie einen neuen Schlüssel und widerrufen den alten. Möchten Sie Alarme sofort erhalten, statt sie ständig abzufragen, folgen Sie Webhook einrichten.

Schlüssel erstellen

Erstellen Sie für jede Anbindung einen eigenen Schlüssel. Dann widerrufen Sie einen, ohne die anderen Anbindungen zu treffen. Jeder Schlüssel hat außerdem ein eigenes Limit von 100 Anfragen pro Minute.

1. Einstellungen öffnen

   Gehen Sie zu Einstellungen > API-Schlüssel.

2. Fenster öffnen

   Klicken Sie rechts oben auf Neuer Schlüssel.

3. Namen eingeben

   Geben Sie bei Name einen Namen ein, an dem Sie die Anbindung erkennen, zum Beispiel Energiebericht Büro.

4. Berechtigungen aktivieren

   Aktivieren Sie unter Berechtigungen die Berechtigungen, die die Anbindung braucht. Erstellen funktioniert erst mit einem Namen und mindestens einer Berechtigung.

5. Schlüssel erstellen

   Klicken Sie auf Erstellen. Das Fenster zeigt den Schlüssel mit dem Hinweis Kopieren Sie diesen Schlüssel jetzt. Sie können ihn später nicht mehr abrufen.

6. Schlüssel kopieren

   Klicken Sie rechts neben dem Schlüssel auf das Symbol mit den zwei Quadraten. Das Portal meldet Kopiert.

7. Schlüssel aufbewahren

   Fügen Sie den Schlüssel in die Software ein, die ihn verwendet, oder in einen Passwort-Tresor.

8. Fenster schließen

   Klicken Sie auf Schließen. Der Schlüssel steht danach mit dem Status Aktiv in der Liste.

Der Schlüssel besteht aus mlk_ und 64 Zeichen danach. ModbusCloud speichert nur einen Hash des Schlüssels und die ersten 12 Zeichen. Diese 12 Zeichen stehen in der Liste bei Prefix. Haben Sie den Schlüssel verloren, erstellen Sie einen neuen und widerrufen den alten.

Schlüssel testen

Der Block Verbindung testen zeigt, ob ein Schlüssel funktioniert und was er darf. Er steht auf derselben Seite, unter der Schlüsselliste.

1. Schlüssel einfügen

   Fügen Sie den Schlüssel in das Feld unter Verbindung testen ein.

2. Verbindung testen

   Klicken Sie auf Testen. Stimmt der Schlüssel, heißt der Block danach API Explorer. Darin steht Schlüssel validiert mit dem Namen, der Organisation und den Berechtigungen des Schlüssels.

3. Kategorie öffnen

   Klicken Sie im Block API Explorer auf eine Kategorie, zum Beispiel Registers.

4. Endpoint ausprobieren

   Klicken Sie bei einem Endpoint mit GET auf Diesen Endpoint testen. Das Portal sendet die Anfrage mit dem Schlüssel an die API und zeigt die Antwort darunter.

Ist der Schlüssel unbekannt, widerrufen oder nicht vollständig kopiert, steht dort Verbindung fehlgeschlagen mit dem HTTP-Status, zum Beispiel HTTP 401. Kategorien, für die der Schlüssel keine Berechtigung hat, stehen unter Mit diesem Schlüssel nicht verfügbar. Steht bei einem Endpoint Kein Gateway verfügbar, fehlt dem Schlüssel Gateways lesen oder Ihre Organisation hat noch kein Gateway.

Außerhalb des Portals testen Sie den Schlüssel mit dem Endpoint /introspect. Er gibt den Namen, die Berechtigungen und die Organisation des Schlüssels zurück und funktioniert mit jedem gültigen Schlüssel.

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

Im Demo-Konto erstellen Sie keine Schlüssel. Probieren Sie die API dort mit dem öffentlichen Sandbox-Schlüssel aus dem Quickstart der API-Referenz aus.

Schreiben von Registern erlauben

Die Berechtigung Register schreiben ist ausgegraut und trägt den Zusatz auf Anfrage, solange die Steuerung auf keinem Gateway Ihrer Organisation eingeschaltet ist. Die Steuerung beantragen Sie pro Gateway, wie unter Register über das Portal steuern beschrieben.

Ist die Steuerung auf mindestens einem Gateway eingeschaltet, aktivieren Sie Register schreiben bei einem neuen Schlüssel. Das Schreiben über die API funktioniert nur auf den Gateways, auf denen die Steuerung eingeschaltet ist. Auf einem anderen Gateway antwortet die API mit Status 403 und dem Code write_not_enabled, egal welche Berechtigungen der Schlüssel hat.

Schlüssel widerrufen

Ein widerrufener Schlüssel funktioniert sofort nicht mehr. Die nächste Anfrage mit diesem Schlüssel erhält Status 401 mit dem Code api_key_revoked.

Bei Zuletzt verwendet steht das Datum der letzten Anfrage mit einem Schlüssel, auch wenn es ein Test im Portal war. So sehen Sie, welche Schlüssel noch im Einsatz sind. Bei einem Schlüssel, der nie eine Anfrage gestellt hat, steht Nie.

1. Einstellungen öffnen

   Gehen Sie zu Einstellungen > API-Schlüssel.

2. Schlüssel suchen

   Suchen Sie den Schlüssel in der Liste anhand von Name oder der ersten Zeichen bei Prefix.

3. Schlüssel widerrufen

   Klicken Sie rechts in der Zeile auf den roten Papierkorb. Das Portal meldet API-Schlüssel widerrufen und der Status wechselt auf Widerrufen.