Dienste

GET /api/im/services · POST /api/im/services · GET /api/im/services/:id · PATCH /api/im/services/:id · DELETE /api/im/services/:id

Ein Dienst ist etwas, das Ihre Organisation betreibt und das ein Vorfall treffen kann, etwa „Webshop“, „Kundenportal“ oder „Mail“. Jeder Dienst hat eine Kritikalität (critical, high, medium, low), optional ein verantwortliches Team und die Monitore, aus denen er besteht. Das ist das Dienst- und Asset-Inventar, das NIS-2 verlangt (Durchführungsverordnung (EU) 2024/2690, Anhang 12 und 5.2).

Jeder Vorfall trägt serviceId (null = kein Dienst). Gesetzt wird es auf zwei Wegen:

• Automatisch, wenn die eingebaute Monitoring-Brücke einen Vorfall öffnet und dessen Monitor genau einem Dienst Ihrer Organisation gehört. Ein Monitor in zwei Diensten ist mehrdeutig und lässt serviceId leer; Alerts aus anderen Quellen (Webhooks, E-Mail, API) werden nie automatisch zugeordnet.
• Von Hand mit Dienst eines Vorfalls setzen.

:id nimmt die numerische id oder die publicId.

AuthentifizierungAnkerlink kopieren

Lesen darf jede IM-berechtigte Rolle (admin, editor, responder) und jedes organisationsweite API-Token, siehe Authentifizierung. Anlegen, Ändern und Löschen verlangen die Rolle admin der Organisation; ein API-Token läuft mit der Rolle der Person, die es angelegt hat. Andere Rollen erhalten 403 imServiceWriteDenied.

Das Dienst-ObjektAnkerlink kopieren

monitorType ist eines von website (auch Heartbeat- und Browser-Monitore), dns, icmp, smtp, ssh, tcp, ftp, imap_pop. Jede Art hat eigene IDs, ein Monitor ist deshalb immer das Paar monitorType + monitorId.

Dienste auflistenAnkerlink kopieren

GET /api/im/services

curl "$BASE_URL/api/im/services" \
  -H "Authorization: Bearer $TOKEN"

200 OK, nach Namen sortiert:

{
  "items": [
    {
      "id": 4,
      "publicId": "0d7c6a0e-6f43-4d3b-9b1e-2a8f1d1c5e77",
      "organizationId": 1,
      "name": "Webshop",
      "description": "Shop und Kasse",
      "criticality": "critical",
      "ownerTeamId": 3,
      "monitors": [
        { "monitorType": "website", "monitorId": 46, "monitorName": "shop.example.com" },
        { "monitorType": "dns", "monitorId": 9, "monitorName": "example.com DNS" }
      ],
      "createdAt": "2026-10-25T08:00:00.000Z",
      "updatedAt": "2026-10-25T08:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 50
}

Einen Dienst abrufenAnkerlink kopieren

GET /api/im/services/:id liefert einen Dienst in derselben Form.

Dienst anlegenAnkerlink kopieren

POST /api/im/services

Unbekannte Felder werden mit 400 invalidRequestBody abgewiesen.

curl -X POST "$BASE_URL/api/im/services" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Webshop",
    "criticality": "critical",
    "ownerTeamId": 3,
    "monitors": [{ "monitorType": "website", "monitorId": 46 }]
  }'

201 Created mit dem Dienst.

Dienst ändernAnkerlink kopieren

PATCH /api/im/services/:id

Merge-Patch: nur die zu ändernden Felder senden (dieselben Felder und Regeln wie beim Anlegen). null leert description oder ownerTeamId. monitors ersetzt die ganze Menge; [] entfernt alle Monitore. Antwort 200 OK mit dem Dienst.

curl -X PATCH "$BASE_URL/api/im/services/4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "criticality": "high" }'

Dienst löschenAnkerlink kopieren

DELETE /api/im/services/:id antwortet 204 No Content. Die Monitor-Zuordnungen gehen mit; Vorfälle bleiben und verlieren nur den Bezug (serviceId wird null).

Jedes Anlegen, Ändern und Löschen landet mit den geänderten Feldern im Audit-Protokoll der Organisation.

Häufige FehlerAnkerlink kopieren

• 401 Unauthorized ohne Anmeldung
• 403 Forbidden (imAccessDenied, imNotEnabled) ohne IM-Zugang oder wenn Incident Management nicht aktiviert ist
• 403 Forbidden (imServiceWriteDenied) wenn jemand ohne Admin-Rolle anlegt, ändert oder löscht
• 400 Bad Request (invalidRequestBody) bei unbekannten Feldern oder falschen Typen; (invalidIdentifier) wenn :id weder ID noch UUID ist
• 404 Not Found (imServiceNotFound) wenn es den Dienst nicht gibt oder er einer anderen Organisation gehört
• 404 Not Found (imTeamNotFound, imServiceMonitorNotFound) für ein Team oder einen Monitor außerhalb Ihrer Organisation
• 409 Conflict (imServiceNameTaken) wenn der Name schon vergeben ist