API-Schlüssel anlegen: Fremdsysteme Störungen melden lassen

Nicht jede Störung meldet ein Mensch. Ein IT-Dienstleister betreibt eigene Tickets, eine Überwachungssoftware bemerkt Ausfälle, eine Bau-Pipeline meldet Änderungen. Diese Systeme melden über die Schnittstelle von knooing, und jedes braucht dafür einen API-Schlüssel. Der Schlüssel ersetzt die Anmeldung: Wer ihn mitschickt, darf genau das, was Sie beim Anlegen erlauben.

Warum ein Schlüssel je System? Wird ein Schlüssel bekannt oder endet ein Vertrag, sperren Sie genau dieses eine System, ohne die anderen zu stören. Außerdem sehen Sie je Schlüssel, wann er zuletzt benutzt wurde, und jede Meldung trägt den Kanal des Schlüssels. So bleibt nachvollziehbar, welches System was gemeldet hat.

Schritt 1: Die Schnittstellen öffnen

In knooing unter Einstellungen, Bereich Integrationen, auf Schnittstellen klicken. Im Reiter Schlüssel sehen Sie alle bisherigen Schlüssel. Rechts oben steht Schlüssel anlegen.

1Schnittstellen öffnen

2Schlüssel anlegen

Schritt 2: Name, Kanal und Berechtigungen festlegen

Im Dialog Schlüssel anlegen tragen Sie zuerst ein, wofür der Schlüssel gedacht ist:

• Name: das Fremdsystem, zum Beispiel Provider-Portal Netzwerk oder Überwachung Rechenzentrum. Der Name erscheint in der Liste und im Protokoll.
• Kanal: Schnittstelle/Provider, Monitoring oder Chat-Bot. Unter diesem Kanal erscheinen die Meldungen im Eingangsbuch und in den Auswertungen.
• Berechtigungen: nur, was das System wirklich braucht. Störungen melden legt neue Meldungen an. Status eigener Meldungen abfragen liest Nummer, Status und Lösung der Meldungen dieses Schlüssels. Changes aus einer Pipeline melden und Monitoring-Ereignisse einliefern sind für die jeweiligen Systeme.

Warum so wenig Rechte wie möglich? Ein Schlüssel liegt beim Fremdsystem, also außerhalb Ihrer Kontrolle. Darf er nur melden, kann auch ein entwendeter Schlüssel nichts lesen oder ändern. Bestehende Vorgänge ändert die Schnittstelle ohnehin nie: Status, Priorität und Zuweisung bleiben beim Servicedesk.

1Name des Fremdsystems

2Nur nötige Berechtigungen

3Ablauf und erlaubte Adressen

4Anlegen

Schritt 3: Wie Meldungen weiterlaufen

Zwei Angaben entscheiden, was mit einer Meldung dieses Schlüssels passiert:

• Vorgang sofort anlegen (Auto-Anlage): Ist die Eingangskontrolle für Schnittstellen eingeschaltet, warten Meldungen normalerweise im Eingangsbuch, bis der Servicedesk sie prüft. Mit Auto-Anlage entsteht der Vorgang trotzdem sofort, sofern der Service feststeht. Ist die Eingangskontrolle aus, entsteht ohnehin immer ein Vorgang.
• Standard-Service: Gilt, wenn eine Meldung keinen Service mitschickt. So landet auch eine knappe Meldung gleich beim richtigen Team.

Beispiel: Die Überwachung meldet zuverlässig und immer mit Service. Ihr Schlüssel bekommt die Auto-Anlage. Das Portal eines neuen Dienstleisters meldet noch unsauber, dort bleibt die Auto-Anlage aus, bis der Servicedesk den Meldungen vertraut.

Schritt 4: Ablauf, Anfragegrenze und erlaubte Adressen

Diese Angaben sind optional, sie begrenzen aber den Schaden, falls ein Schlüssel in falsche Hände gerät:

• Ablaufdatum: Der Schlüssel gilt bis zum Ende dieses Tages. Sinnvoll für befristete Verträge oder Projekte.
• Anfragen je Minute: Weitere Anfragen in derselben Minute lehnt die Schnittstelle ab. Das schützt davor, dass ein fehlerhaftes System den Servicedesk mit Meldungen flutet.
• Erlaubte IP-Adressen: Einzelne Adressen oder Netze, von denen das System meldet. Von anderswo gilt der Schlüssel dann nicht.

Danach auf Anlegen klicken.

Schritt 5: Den Schlüssel kopieren und sicher übergeben

knooing zeigt den neuen Schlüssel genau einmal an. Mit Kopieren übernehmen Sie ihn und geben ihn an die Person, die das Fremdsystem einrichtet. Danach auf Fertig klicken.

!Wird nur jetzt angezeigt

5Kopieren

Warum nur einmal? knooing speichert den Schlüssel selbst nicht, sondern nur einen daraus berechneten Prüfwert. Selbst wer Zugriff auf die Datenbank hätte, könnte den Schlüssel daraus nicht zurückgewinnen. Geht er verloren, legen Sie einfach einen neuen an und widerrufen den alten.

Schritt 6: Schlüssel prüfen und widerrufen

In der Liste sehen Sie je Schlüssel Präfix, Kanal, Berechtigungen, Auto-Anlage, Standard-Service, Zuletzt benutzt, Läuft ab und Status. Am Präfix erkennen Sie einen Schlüssel wieder, ohne ihn ganz zu kennen.

6Stand je Schlüssel

×Widerrufen

Mit Widerrufen sperren Sie einen Schlüssel dauerhaft. Jedes System, das ihn nutzt, kann danach nichts mehr melden. Der Widerruf lässt sich nicht rückgängig machen. Bereits gemeldete Vorgänge bleiben erhalten.

Wann widerrufen? Sobald ein Vertrag endet, ein System abgelöst wird oder der Verdacht besteht, dass der Schlüssel bekannt geworden ist. Ein Blick auf Zuletzt benutzt hilft beim Aufräumen: Ein Schlüssel, der seit Monaten nicht benutzt wurde, wird meist nicht mehr gebraucht.

Wenn etwas nicht klappt

• Das Fremdsystem erhält eine Ablehnung wegen fehlender Anmeldung. Der Schlüssel fehlt im Kopffeld X-API-Key, ist falsch kopiert, abgelaufen oder widerrufen. Prüfen Sie Status und Ablauf in der Liste.
• Das Fremdsystem erhält eine Ablehnung wegen fehlender Berechtigung. Dem Schlüssel fehlt die passende Berechtigung, zum Beispiel Status abfragen. Legen Sie einen neuen Schlüssel mit der Berechtigung an und widerrufen Sie den alten.
• Meldungen werden abgewiesen, weil zu viele Anfragen kamen. Die Grenze der Anfragen je Minute ist erreicht. Erhöhen Sie sie beim nächsten Schlüssel oder lassen Sie das System langsamer senden.
• Meldungen kommen an, werden aber kein Vorgang. Die Eingangskontrolle für Schnittstellen ist eingeschaltet, und die Auto-Anlage ist aus oder der Service fehlt. Die Meldungen warten im Eingangsbuch.