REST-API und MCP

Handbuch · Datenquellen einrichten · Adapter · Ingest-Referenz

Verfügbarkeit

Stand 19.09.2026: Die erweiterte Fach-API, der Push-Ingest und die neuen Adapter sind umgesetzt, aber noch nicht im veröffentlichten Kundenupdate v1.25.0 enthalten. Dieses Kapitel beschreibt diese Erweiterung. Maßgeblich für eine installierte Instanz ist deren eigene OpenAPI-Spezifikation. Ein Handbuch-Update aktualisiert die Anwendung nicht.

API-Zugang einrichten

Als Administrator Einstellungen > API-Zugänge öffnen.
Pro Anwendung einen Schlüssel mit Namen, Ablaufdatum und den benötigten Scopes erstellen.
Den einmalig angezeigten Schlüssel in einem Secret Store oder der geschützten Umgebung des Clients hinterlegen. Er lässt sich später nicht erneut anzeigen.
Die OpenAPI-Spezifikation der eigenen Instanz herunterladen und einen Leseaufruf prüfen.

Jeder Schlüssel hat einen eigenen technischen Benutzer. Änderungen erscheinen mit dieser Identität im Audit-Protokoll. Widerrufen beendet den Zugriff sofort. Bestehende Schlüssel erhalten durch ein Update keine zusätzlichen Scopes.

Alle Pfade in diesem Kapitel beziehen sich auf die eigene ISMS-Instanz, beispielsweise https://isms.example.org, nicht auf diese Handbuch-Website. Die API akzeptiert Bearer-Schlüssel; eine Browser-Anmeldung ersetzt den Schlüssel nicht.

$env:ISMS_URL = 'https://isms.example.org'
# ISMS_API_KEY wurde aus dem Secret Store in die Prozessumgebung geladen.
$headers = @{ Authorization = "Bearer $env:ISMS_API_KEY" }
Invoke-RestMethod "$env:ISMS_URL/api/v1/assets?perPage=10" -Headers $headers

Dieser Aufruf benötigt assets:read.

Dokumentation und Downloads

Pfad auf der eigenen Instanz	Zugriff und Inhalt
`/settings/api-keys/docs`	Eingebettete Anleitung, als Administrator angemeldet
`/settings/api-keys/openapi.json`	OpenAPI-Download über die Administrator-Sitzung
`/api/v1/openapi.json`	OpenAPI 3.1 mit gültigem Bearer-Schlüssel
`/settings/api-keys/adapters.zip`	Beispiele für HTTPS-Versand, Assetexport und Veeam samt deutscher und englischer Anleitung
`/settings/api-keys/mcp-server.zip`	Lokaler MCP-Server samt Einrichtungshinweisen

OpenAPI enthält die konkreten Operationen, Parameter, Pflichtfelder, Antworten und Fehler. x-required-scopes nennt die Rechte; zusätzliche Bedingungen stehen in der Operationsbeschreibung. x-domain-schema beschreibt die fachlichen Wertebereiche. Verwende für einen Client die Spezifikation seiner Zielinstanz.

Fachbereiche

Die Fach-API stellt die vorgesehenen Arbeitsabläufe bereit. Sie ist kein direkter Tabellenzugriff. Validierung, Konfliktprüfung, Freigaben, Dokumentverschlüsselung und Audit-Protokoll gelten auch für API-Aufrufe.

Pfade unter `/api/v1`	Daten und Arbeitsabläufe
`/assets`, `/assets/{id}/records`	Assets, Abhängigkeiten, Verträge, Dokumente und Wiederanlaufangaben
`/vendors`, `/vendors/{id}/records`	Dienstleister, Kontakte, Verträge, Bewertungen und Unterauftragnehmer
`/risks`, `/measures`	Risiken, Akzeptanz, Maßnahmen, Abschluss und Wirksamkeit
`/scope`, `/scope/elements`, `/scope/history`	Geltungsbereich, Elemente, Schnittstellen, Versionen und Freigaben
`/soa`, `/soa/snapshots`, `/soa/gap-analysis`	Controls, Bewertungen, Nachweise, Verknüpfungen und Bewertungsstände
`/bcm`, `/bcm/exercises/{id}`, `/recovery-plan`	Prozesse, BIA, Wiederanlauf, Übungen, Feststellungen und Aufgaben
`/backup-jobs`	Backup-Aufträge, Läufe, Restore-Testvorgaben und Testnachweise
`/audits`, `/reviews`	Auditprogramme, Audits, Findings, Management-Reviews und Entscheidungen
`/incidents`	Vorfälle, Verlauf, Einstufung, dokumentierte Meldungen und Nachweise
`/policies`, `/policies/{id}/translations`	Richtlinien, Versionen, Freigaben und Übersetzungen
`/trainings`, `/emergency`	Schulungen, Teilnahmeverwaltung, Notfallpläne, Kontakte und Tests
`/processing-activities`, `/processing-activities/toms`	Verarbeitungstätigkeiten, TOMs und Zuordnungen
`/access-requests`, `/user-lifecycle`, `/user-lifecycle/profiles`	Anträge, Entscheidungen, Umsetzung und Berechtigungsprofile
`/users`, `/groups`, `/group-assignments`	Benutzer- und Gruppenreferenzen sowie fachliche Gruppenzuordnungen
`/documents`, `/documents/{id}`, `/audit-log`	Dokumentmetadaten, Downloads und Änderungshistorie
`/integrations`	Quellen, Zuordnungen, Push-Batches, Beobachtungen und Abweichungen

Die vorhandenen Pfade bedeuten nicht, dass jede Ressource beliebige CRUD-Operationen unterstützt. Verfügbare Methoden und Aktionspfade stehen in OpenAPI. Systemadministration, Lizenzierung, Verzeichnis-Konfiguration und Framework-Import bleiben in den Einstellungen. Persönliche Kenntnisnahmen und Selbstbestätigungen dürfen nicht durch technische API-Konten erfolgen.

Berechtigungen

Scope	Verwendung
`<modul>:read`	Daten des Fachmoduls lesen
`<modul>:write`	Anlegen und Bearbeiten; zusätzliche Fachaktionen benötigen auch `read`
`<modul>:approve`	Fachliche Entscheidungen und Abschlüsse, zusätzlich zu den erforderlichen Lese-/Schreibrechten
`<modul>:delete`	Vorgesehene Löschaktionen
`directory:read`	Benutzerreferenzen lesen
`groups:read`, `groups:write`	Gruppenreferenzen und fachliche Zuordnungen gemäß Operation
`documents:read`, `documents:write`, `documents:delete`	Dokumentzugriff zusammen mit den Rechten des Fachobjekts
`audit-log:read`	Audit-Protokoll lesen
`integrations:read`, `integrations:manage`, `ingest:write`	Getrennte Rollen für Auswertung, Einrichtung und Datenlieferung

Die Modulnamen entsprechen beispielsweise assets, backup-jobs, processing-activities und user-lifecycle-profiles. Die genaue Kombination ist je Operation dokumentiert.

Scopes gelten instanzweit, einschließlich Entwürfen und Fachversionen. Sie übernehmen keine persönliche Rollen- oder Gruppensichtbarkeit. assets:read erlaubt aus Kompatibilitätsgründen auch Benutzer- und Dienstleisterreferenzen; technische Assetdetails können entschlüsselt zurückgegeben werden. Verknüpfte Fachabschnitte benötigen zusätzliche Leserechte, etwa bcm:read für Wiederanlaufnotizen unter /assets/{id}/records. Für echte Mandantentrennung getrennte Instanzen verwenden.

Lesen, Anlegen und Bearbeiten

Listen haben modulspezifische Filter und Seitengrößen. Bei Fachlisten beginnt page bei 1; Integrationslisten verwenden offset und limit. Ein fehlender verknüpfter Abschnitt kann auf einen fehlenden Lesescope zurückgehen.

GET liest den dokumentierten Datenabschnitt.
POST auf einer Sammlung legt einen Datensatz an.
PUT übermittelt ein vollständiges Bearbeitungsformular. Fehlende optionale Felder können vorhandene Werte leeren.
Assets und Dienstleister behalten ihre partiellen PATCH-Endpunkte; null leert ein Feld.
Fachentscheidungen verwenden eigene POST-Pfade unter /{id}/actions/….

Bei Fachaktionen werden JSON-Skalare in Formularwerte übertragen, Arrays in wiederholte Felder und null in einen leeren Wert. Vor einem Update den aktuellen Stand lesen und die für die Operation vorgesehenen Konfliktmarken wie baseUpdatedAt, expectedUpdatedAt oder baseVersion mitsenden. Bei 409 neu lesen und Änderungen abgleichen.

Fachaktionen antworten üblicherweise mit HTTP 200 und success: true; die bestehende Asset-Anlage verwendet 201. Eine zurückgegebene id kann das angesprochene Elternobjekt bezeichnen. Den resultierenden Fachstand anschließend über den dokumentierten Lese-Endpunkt prüfen. Anlagen über die Fach-API sind nicht automatisch idempotent: Eine verlorene Antwort rechtfertigt keine ungeprüfte Wiederholung. Für wiederholbare Quellenimporte den Push-Ingest verwenden.

Assets anhand externer IDs abgleichen

Die klassische Asset-API verwendet externalSource und externalId immer gemeinsam. Der Abgleich ignoriert Groß-/Kleinschreibung und äußere Leerzeichen.

Mit GET /api/v1/assets?externalSource=glpi&externalId=srv-001 suchen.
Ohne Treffer mit POST /api/v1/assets anlegen. Pflichtfelder sind name, assetType, criticality von 1 bis 5 und ein gültiger ownerId.
Bei vorhandenem Asset mit PATCH /api/v1/assets/{id} aktualisieren; updatedAt aus dem Lesen als expectedUpdatedAt mitsenden.
Bei 409 duplicateExternalRef die details.existingId auswerten und den vorhandenen Datensatz lesen.

Das ist ein clientseitiger Abgleich, kein einzelner Upsert-Endpunkt. Die Quellen-/Binding-Zuordnung des Push-Ingest ist ein eigener Vertrag. Bereits vorhandene Assets dort ausdrücklich zuordnen.

Backup-Läufe und Restore-Tests

Ein vorhandener Backup-Auftrag kann einen Sicherungslauf aufnehmen. Der Schlüssel braucht backup-jobs:read und backup-jobs:write. Die Zeitwerte im Beispiel durch tatsächliche Daten ersetzen.

$jobId = 'UUID-DES-BACKUP-AUFTRAGS'
$run = @{
    startedAt = '2026-09-19T01:00:00Z'
    finishedAt = '2026-09-19T01:10:00Z'
    result = 'successful'
    restorePointAt = '2026-09-19T01:00:00Z'
} | ConvertTo-Json
Invoke-RestMethod "$env:ISMS_URL/api/v1/backup-jobs/$jobId/actions/add-run" `
    -Method Post -Headers $headers -ContentType 'application/json' -Body $run

Der Detailabruf liefert backupJob.runs, backupJob.restoreTestDefinitions und executions. Restore-Testabschlüsse und Korrekturen verwenden complete-execution bzw. correct-execution und zusätzlich backup-jobs:approve. Die jeweiligen Pflichtangaben stehen in OpenAPI. Eine Korrektur erzeugt einen neuen Nachweis; ein abgeschlossener Test wird nicht überschrieben.

Ingest-Beobachtungen sind davon getrennt. Ein backup_run-Ereignis legt nicht automatisch einen fachlichen Sicherungslauf an; ein restore_test-Ereignis schließt keine Testdurchführung ab. Die Bedeutung eines erfolgreichen Jobs für RPO und Restore erläutert das Adapter-Kapitel.

Dokumente und Nachweise

Dateien über die Upload-Aktion des Fachobjekts senden, beispielsweise POST /api/v1/assets/{id}/actions/upload-document mit multipart/form-data und Dateifeld file. Neben den Fachrechten ist documents:write erforderlich. Bei Multipart den Header Origin: https://isms.example.org mit dem tatsächlichen Origin der Instanz ohne abschließenden Schrägstrich senden. Die Formularschutzprüfung läuft vor der API-Authentifizierung.

Downloads benötigen documents:read und Leserecht für das zugehörige Fachobjekt. Dokumente werden verschlüsselt gespeichert. JSON-Anfragen dürfen höchstens 1 MiB, Multipart-Anfragen höchstens 26 MiB umfassen; die Dateigrenzen des Fachmoduls gelten zusätzlich. Ingest-Evidence enthält dagegen kurze Nachweise mit optionalem Link und Hash, keine hochgeladenen Dateien.

Fehler und Abrufgrenzen

{
  "code": "conflict",
  "message": "…",
  "details": { "reason": "sourceRevision" }
}

Clients werten HTTP-Status und code aus, beim Ingest zusätzlich details.reason. message ist über Accept-Language: de oder en lokalisiert.

Status	Behandlung
`400`	JSON, Pflichtfelder, Werte und Referenzen prüfen
`401`	Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen
`403`	Erforderliche Scopes fehlen
`404`	Pfad, Objekt-ID und installierten Funktionsumfang prüfen; beim Ingest auch die Schlüsselzuordnung zur Quelle
`409`	Konflikt auswerten und aktuellen Fachstand lesen
`413` / `415`	Anfragegröße bzw. Content-Type korrigieren
`429`	`Retry-After` beachten; maximal 120 Anfragen pro Minute und Schlüssel

Für Statusänderungen ist Polling erforderlich; Webhooks sind nicht enthalten.

MCP-Clients

Der mitgelieferte MCP-Server läuft beim Anwender und verbindet sich per HTTPS mit der Instanz. ZIP unter API-Zugänge herunterladen, entpacken und gemäß dessen README installieren. Im MCP-Client node mit dem Pfad zu index.js starten und ISMSLITE_URL sowie ISMSLITE_API_KEY aus einer geschützten Konfiguration bereitstellen.

Voraussetzung für das MCP-Paket ist Node.js ab Version 20. Im entpackten Verzeichnis einmal npm install ausführen. Diese Installation betrifft den lokalen MCP-Client, nicht den ISMS-Server und nicht die separaten Push-Adapter.

Neben den bisherigen Asset-/Dienstleister-Werkzeugen stellt die Erweiterung list_api_operations und call_api_operation bereit. Diese nutzen die OpenAPI-Spezifikation der Zielinstanz für unterstützte JSON-Operationen mit GET, POST und PUT. Datei-Uploads benötigen einen geeigneten HTTP-Client. Auch ein KI-Client darf nur die Scopes seines Schlüssels verwenden; Freigaberechte deshalb bewusst vergeben.