Deliver ITAM data via the API: usage, lifecycle, SBOM and device values

Viele Angaben zu Ihren Geräten und Systemen kennt der Dienstleister, der sie betreibt, besser als Sie. Er weiß, wer sich wann an einer Software angemeldet hat und wann der Hersteller den Support beendet. Er kennt auch die Bibliotheken in einem System und den Preis eines Geräts. Statt diese Angaben abzutippen, schickt sein System sie über die Schnittstelle direkt an knooing. knooing prüft jede Lieferung nach denselben Regeln wie die Masken und schreibt nur, was passt.

Diese Anleitung ist für die Person, die die Lieferung einrichtet, und für die Technik des Dienstleisters. Am Ende hat der Dienstleister einen eigenen Schlüssel, kennt die vier Lieferwege, und Sie sehen in knooing, was angekommen ist. Wie Schlüssel allgemein funktionieren, steht in API-Schlüssel anlegen.

Die wichtigsten Begriffe

• Schlüssel: das Passwort, mit dem sich das System des Dienstleisters bei knooing ausweist. Jeder Lieferant bekommt einen eigenen.
• Berechtigung (Scope): was ein Schlüssel darf. Beispiel: lifecycle:write darf Lebenszyklustermine liefern, aber keine SBOM.
• Gerätebezug: woran knooing das Gerät oder System erkennt: ciNumber (Inventarnummer), hostname (Name) oder serialNumber (Seriennummer). knooing sucht genau, nie ähnlich. Tragen zwei Systeme denselben Namen, weist es den Eintrag ab.
• Teilweise angenommen: Eine Lieferung mit vielen Einträgen wird nicht als Ganzes abgelehnt. Fehlerhafte Einträge stehen mit Grund in der Antwort, die übrigen sind geschrieben.

Schritt 1: Einen Schlüssel mit den Lieferberechtigungen anlegen

Klicken Sie in der Seitenleiste unten auf Einstellungen, dann auf Integrationen und auf Schnittstellen. Klicken Sie im Reiter Schlüssel auf Schlüssel anlegen. Tragen Sie bei Name das liefernde System ein, etwa „Dienstleister Arbeitsplatz“. Den Kanal lassen Sie, wie er ist.

Unter Berechtigungen sind zu Beginn Störungen melden und Status eigener Meldungen abfragen angehakt. Nehmen Sie diese Haken weg, wenn der Dienstleister keine Störungen melden soll. Haken Sie dann an, was er liefern soll (1):

• Anmeldungen als Nutzung melden (software-usage:write)
• Lebenszyklustermine liefern (lifecycle:write)
• SBOM liefern (sbom:write)
• Anschaffung und Nachhaltigkeit liefern (assets:write)

Klicken Sie auf Anlegen (2).

12

Warum nur die nötigen Berechtigungen? Ein Schlüssel, der nur Lebenszyklustermine liefern darf, kann keine Anschaffungswerte ändern. Ein Fehler im System des Dienstleisters bleibt so auf seine Daten begrenzt.

Beispiel: Julia Beispiel richtet für den Dienstleister, der die Arbeitsplätze und Server der Beispiel GmbH betreut, den Schlüssel „Dienstleister Arbeitsplatz“ mit allen vier Berechtigungen ein.

Schritt 2: Den Schlüssel kopieren und übergeben

knooing zeigt den neuen Schlüssel genau einmal an. Klicken Sie auf Kopieren und dann auf Fertig. Geben Sie den Schlüssel über einen sicheren Weg weiter, etwa einen Passwort-Tresor, nicht im Klartext per E-Mail.

Danach steht der Schlüssel in der Liste mit Name, Zuletzt benutzt und dem Status aktiv. Unter Aufrufe sehen Sie später jede Lieferung dieses Schlüssels. Mit Widerrufen sperren Sie ihn sofort. Wie das im Einzelnen aussieht, steht in API-Schlüssel anlegen.

Warum nur einmal? knooing speichert den Schlüssel selbst nicht. Geht er verloren, legen Sie einen neuen an und widerrufen den alten.

Beispiel: Julia Beispiel legt den Schlüssel im Passwort-Tresor ab und gibt ihn dort für den Dienstleister frei.

Schritt 3: Die Lieferung senden

Das System des Dienstleisters sendet den Schlüssel bei jedem Aufruf im Kopffeld X-API-Key. Pfade, Berechtigungen und Beispiele stehen auch in knooing, unter Schnittstellen im Reiter Dokumentation. Dort heißen die Abschnitte Anmeldungen als Softwarenutzung melden, Lebenszyklustermine liefern, SBOM eines Systems liefern und Anschaffung und Nachhaltigkeit je Asset liefern. Die Adresse Ihres knooing steht dort neben Basisadresse: und in jedem Aufruf mit curl. Unten steht stattdessen <Adresse Ihres knooing-Systems>.

Die vier Pfade und die Berechtigung, die der Schlüssel dafür braucht:

• Anmeldungen als Nutzung: POST /api/v1/software-usage/sign-ins, Berechtigung software-usage:write
• Lebenszyklustermine: PUT /api/v1/lifecycle/configuration-items, Berechtigung lifecycle:write
• SBOM eines Systems: POST /api/v1/sbom, Berechtigung sbom:write
• Anschaffung und Nachhaltigkeit: PUT /api/v1/assets/values, Berechtigung assets:write

Anmeldungen. Für Software, die sich nicht über Microsoft Entra ID anmeldet, etwa auf einem Terminalserver: je Anmeldung Gerät, Produkt und Zeitpunkt. In coveredProducts nennt das System die Produkte, die es vollständig erfasst. Erst dann belegt eine fehlende Anmeldung, dass ein Produkt nicht genutzt wird.

curl -X POST '<Adresse Ihres knooing-Systems>/api/v1/software-usage/sign-ins' \
  -H 'X-API-Key: <Schlüssel>' -H 'Content-Type: application/json' \
  --data '{
    "system": "Terminalserver",
    "coveredProducts": [{ "vendor": "Muster Logistik", "name": "Routenplaner" }],
    "events": [{ "device": { "hostname": "nb-lager12" },
      "product": { "vendor": "Muster Logistik", "name": "Routenplaner" },
      "signedInAt": "2026-10-12T08:15:00Z" }]
  }'

Lebenszyklustermine. Je System, Produkt und Version das Ende des Supports (endOfSupportAt) und das Lebensende (endOfLifeAt). Dazu kommen in source der Name der Quelle und auf Wunsch in reference ein Beleg, etwa die Seite des Herstellers. Mit "mode": "merge" ergänzt und aktualisiert die Lieferung. Mit "mode": "replace" ist sie der vollständige Stand dieser Quelle für jedes gelieferte System, und Produkte, die darin fehlen, entfallen.

curl -X PUT '<Adresse Ihres knooing-Systems>/api/v1/lifecycle/configuration-items' \
  -H 'X-API-Key: <Schlüssel>' -H 'Content-Type: application/json' \
  --data '{
    "source": "Werkzeug Dienstleister",
    "mode": "merge",
    "items": [
      { "ci": { "hostname": "srv-portal01" },
        "product": { "vendor": "Muster Web", "name": "Webserver", "version": "2.4" },
        "endOfSupportAt": "2027-06-30", "endOfLifeAt": "2027-12-31",
        "reference": "https://muster-web.beispiel.test/lebenszyklus/webserver-2-4" },
      { "ci": { "hostname": "srv-portal01" },
        "product": { "vendor": "Muster Java", "name": "Java-Laufzeit", "version": "17" },
        "endOfSupportAt": "2029-09-30", "endOfLifeAt": null }
    ]
  }'

SBOM. Der Körper ist die Stückliste selbst, als CycloneDX JSON oder SPDX 2.x JSON. Das System steht in der Adresse, etwa ?hostname=srv-portal01 oder ?serialNumber=…. Die Komponenten ersetzen den bisherigen Stand dieses Systems.

curl -X POST '<Adresse Ihres knooing-Systems>/api/v1/sbom?hostname=srv-portal01' \
  -H 'X-API-Key: <Schlüssel>' -H 'Content-Type: application/vnd.cyclonedx+json' \
  --data-binary @srv-portal01.cdx.json

Anschaffung und Nachhaltigkeit. Je Gerät die Werte, die auch die Maske am Gerät kennt. Mit "dryRun": true zeigt die Antwort je Gerät den bisherigen und den neuen Wert, ohne etwas zu schreiben. Nachhaltigkeitsangaben legt knooing mit der Lieferung als Quelle ab.

curl -X PUT '<Adresse Ihres knooing-Systems>/api/v1/assets/values' \
  -H 'X-API-Key: <Schlüssel>' -H 'Content-Type: application/json' \
  --data '{
    "dryRun": true,
    "source": "Dienstleister Arbeitsplatz",
    "items": [{ "asset": { "serialNumber": "SN-0043" },
      "values": { "purchasePrice": 1349.00, "purchaseCurrency": "EUR",
        "purchaseDate": "2026-09-20", "usefulLifeMonths": 48 } }]
  }'

Danach antwortet knooing mit dem Status 200, bei einer SBOM mit 201, und einem JSON-Körper, siehe Schritt 4. Die vollständige Beschreibung aller Felder öffnet OpenAPI-Beschreibung neben Basisadresse: im Reiter Dokumentation.

Warum vier Wege statt einer Datei? Jede Art von Daten hat ihre eigenen Regeln und ihren eigenen Ort in knooing. Getrennte Wege mit getrennten Berechtigungen halten Fehler auseinander.

Beispiel: Der Dienstleister sendet jede Nacht die Anmeldungen des Terminalservers, einmal in der Woche die Lebenszyklustermine aus seinem Werkzeug und nach jeder neuen Version die SBOM des Bestellportals. Neue Notebooks meldet er mit Preis und Lieferdatum.

Schritt 4: Die Antwort lesen

Jede Antwort zählt, was angekommen ist, was übernommen und was abgewiesen wurde. Abgewiesene Einträge stehen mit ihrer Position und dem Grund darin. Im Beispiel der Lebenszyklustermine mit einem dritten Eintrag für ein System, das es nicht gibt:

{ "received": 3, "accepted": 2, "rejected": 1, "systemsUpdated": 1, "productsRemoved": 0,
  "items": [
    { "index": 0, "status": "ok", "ciId": "cmv6…" },
    { "index": 1, "status": "ok", "ciId": "cmv6…" },
    { "index": 2, "status": "rejected", "error": "Kein Konfigurationselement mit Name „srv-portal99“." } ] }

Die anderen Wege antworten genauso aufgebaut:

• Anmeldungen: received, accepted, signalsWritten (je Installation und Tag eine Nutzung) und products mit coveredSince, dem Tag, ab dem das Produkt als erfasst gilt.
• SBOM: das erkannte System unter ci, format, die Zahl der übernommenen Komponenten unter imported und übersprungene Komponenten unter rejectedComponents.
• Anschaffung und Nachhaltigkeit: je Gerät status (ok, unchanged oder error), die Änderungen mit before und after und errors. Bei einem Gerät mit Preis, Datum und Nutzungsdauer steht dort auch depreciationMethod mit straight_line, also linear, wie beim Erfassen von Hand.

Korrigieren Sie abgewiesene Einträge und senden Sie sie erneut. Was schon da ist, schreibt knooing nicht doppelt.

Warum teilweise annehmen? Ein einziger falscher Name soll nicht die Termine von hundert anderen Systemen aufhalten.

Beispiel: Der Dienstleister hat „srv-portal99“ geliefert, ein System, das die Beispiel GmbH nicht kennt. Die beiden Einträge für srv-portal01 sind übernommen. Er prüft den Namen in seinem Werkzeug.

Schritt 5: Das Ergebnis in knooing prüfen

Jede Lieferung steht danach an ihrem Ort in knooing:

• Lebenszyklustermine: Öffnen Sie in der Seitenleiste Konfigurationsverwaltung und darin Bestand, suchen Sie das System und öffnen Sie es. Unten auf der Systemseite steht der Block Lebenszyklus aus Quellen. Er nennt je Produkt Version, Support endet, Lebensende, Quelle und Geliefert am. maßgeblich (1) markiert den frühesten Termin. Er gilt als Termin des ganzen Systems und erscheint in den Warnungen und Berichten zu EOL und EOS. Unter dem Produkt steht der Beleg (2), eine Adresse lässt sich anklicken. Unter Quelle (3) steht der Name aus source. Fehlt ein Termin, steht dort „nicht angekündigt“.

123

• Anmeldungen: Im Reiter Lizenzoptimierung des Bestands steht das Produkt unter Erfasste Produkte mit der Quelle „Schnittstelle“ (1) und dem Tag, ab dem es erfasst ist. Was das für die Rückgewinnung bedeutet, steht in Nutzung aus Anmeldungen zuordnen, Schritt 4.

1

• SBOM: Auf der Systemseite steht der Block SBOM-Komponenten mit der eingespielten Datei und ihren Komponenten, siehe Software und SBOM eines Systems ansehen.
• Anschaffung und Nachhaltigkeit: Auf der Geräteseite stehen die Werte in den Kästen Anschaffung und Nachhaltigkeit. Unter Quellenangabe, ungeprüft steht die abgelegte Lieferung.

Jede Änderung steht außerdem im Änderungsverlauf des Systems oder Geräts, mit dem Schlüssel als Auslöser.

Warum am Ziel prüfen? Die Antwort sagt, dass geschrieben wurde. Am System sehen Sie, was das für Ihren Bestand bedeutet, etwa welcher Termin jetzt gilt.

Beispiel: Julia Beispiel öffnet srv-portal01. Der Webserver 2.4 endet am 30.6.2027 im Support und ist maßgeblich. Die Java-Laufzeit hat kein angekündigtes Lebensende.

Wenn etwas nicht klappt

• Die Antwort hat den Status 401. Der Schlüssel fehlt, ist falsch kopiert, abgelaufen oder widerrufen. Prüfen Sie das Kopffeld X-API-Key und den Status des Schlüssels in der Liste.
• Die Antwort hat den Status 403 mit insufficient_scope. Dem Schlüssel fehlt die Berechtigung für diesen Pfad. Legen Sie einen Schlüssel mit der passenden Berechtigung an.
• „Dem Dienstkonto dieses Schlüssels fehlt das Recht zum Bearbeiten der Konfigurationsverwaltung.“ Die Person, die den Schlüssel angelegt hat, hat dieses Recht nicht mehr. Lassen Sie den Schlüssel von einer Person mit dem Recht neu anlegen.
• „Für Schlüssel mit CMDB-Schreibrecht ist selbst das Recht Konfigurationsverwaltung (Bearbeiten) nötig.“ beim Anlegen. Ihnen fehlt dieses Recht. Bitten Sie Ihre Administration darum.
• „Für diese Aktion ist eine eingerichtete Zwei-Faktor-Authentisierung erforderlich. …“ beim Anlegen. Richten Sie die Zwei-Faktor-Anmeldung in Ihrem Konto ein und legen Sie den Schlüssel danach an.
• „Kein Konfigurationselement mit Name „…“.“ oder mit Seriennummer. Das Gerät oder System steht nicht im Bestand, oder der Name ist anders geschrieben. Erfassen Sie es oder senden Sie die Inventarnummer.
• Ein Eintrag wird wegen mehrerer Treffer abgewiesen. Zwei Systeme tragen denselben Namen. Senden Sie die Inventarnummer oder die Seriennummer.
• Anmeldungen werden mit Grund abgewiesen. Auf dem Gerät ist das gemeldete Produkt nicht installiert, oder Hersteller und Name passen zu keiner Installation. Prüfen Sie im Reiter Software, wie das Produkt dort heißt.