Incident-Rollen zuweisen

Ein Incident hat vier Rollen: commander, tech_lead, comms und assignee. Zwei Endpunkte verwalten, wer sie hält:

• Rolle zuweisen setzt die einzige Inhaberin einer Rolle und ersetzt, wer sie vorher hatte.
• Responder hinzufügen fügt einer Rolle eine weitere Person hinzu, ohne jemanden zu entfernen, und kann sie sofort alarmieren.

Die aktuellen Rolleninhaber stehen in assignments von Incident abrufen. Jede Änderung wird in der Timeline des Incidents vermerkt. Um eine Rolle zu leeren, nutze die Aktion assign von Incidents gesammelt ändern mit userId: null.

AuthentifizierungAnkerlink kopieren

Jede IM-berechtigte Rolle (admin, editor, responder) oder ein organisationsweiter API-Token, siehe Authentifizierung. Incident Management muss für die Organisation aktiviert sein.

Wer zugewiesen werden kann: die Person in userId muss zu deiner Organisation gehören. Bist du nicht Organisations-Admin (ein organisationsweiter API-Token gilt als solcher), muss sie außerdem Mitglied im Team des Incidents sein.

Rolle zuweisenAnkerlink kopieren

POST /api/im/incidents/:id/assign

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/incidents/42/assign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "MFcTjWmYq2LpzR8vK1sXo", "role": "commander" }'

Antwort (Response)Ankerlink kopieren

200 OK: die neue Zuweisung.

{
  "id": 12,
  "incidentId": 42,
  "userId": "MFcTjWmYq2LpzR8vK1sXo",
  "role": "commander",
  "createdAt": "2026-07-17T09:15:00.000Z",
  "user": {
    "name": "Grace Hopper",
    "email": "grace@example.com"
  }
}

user.email ist nur für Organisations-Admins gefüllt (und damit für einen normalen organisationsweiten API-Token); für jede andere Rolle steht dort null.

Häufige FehlerAnkerlink kopieren

• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden (customerScopedTokenForbidden) bei Verwendung eines kunden-gescopten Tokens
• 403 Forbidden (imAccessDenied) wenn die angemeldete Person keine IM-berechtigte Rolle hat
• 403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
• 400 Bad Request (invalidRequestBody) wenn :id keine positive Ganzzahl ist, role fehlt oder unbekannt ist, oder userId fehlt oder leer ist
• 404 Not Found (imIncidentNotFound) wenn der Incident nicht existiert oder zu einer anderen Organisation gehört
• 422 Unprocessable Entity (invalidUserId) wenn userId nicht existiert oder nicht zu deiner Organisation gehört
• 422 Unprocessable Entity (imIncidentAssigneeNotOnTeam) wenn du nicht Organisations-Admin bist und userId nicht Mitglied im Team des Incidents ist

Responder hinzufügenAnkerlink kopieren

POST /api/im/incidents/:id/add-responder

Holt eine weitere Person dazu, etwa eine Spezialistin, die die Eskalations-Tiers nie erreichen würden. Mit notify: true startet ihre Alarmierung sofort, beim aktuellen Tier des Incidents und mit der Dringlichkeit seines Schweregrads.

Das Hinzufügen ist dem Team des Incidents vorbehalten: du musst Mitglied im Team des Incidents oder Organisations-Admin sein. Mit notify: true musst du Team-Admin des Teams oder Organisations-Admin sein. Ein organisationsweiter API-Token erfüllt beides als Organisations-Admin.

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/incidents/42/add-responder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "Zx81KpLmQr7TbVn2WcYdE", "role": "tech_lead", "notify": true }'

Antwort (Response)Ankerlink kopieren

200 OK: die neue Zuweisung und ob die Alarmierung gestartet wurde.

{
  "id": 13,
  "incidentId": 42,
  "userId": "Zx81KpLmQr7TbVn2WcYdE",
  "role": "tech_lead",
  "createdAt": "2026-07-17T09:30:00.000Z",
  "user": {
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "notifyStarted": true
}

notifyStarted spiegelt notify. Die Alarmierung wird nach dem Speichern der Zuweisung auf Best-Effort-Basis eingereiht; scheitert das, bleibt die Zuweisung bestehen und der Fehler wird nur serverseitig protokolliert.

Häufige FehlerAnkerlink kopieren

• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden (customerScopedTokenForbidden) bei Verwendung eines kunden-gescopten Tokens
• 403 Forbidden (imAccessDenied) wenn die angemeldete Person keine IM-berechtigte Rolle hat
• 403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
• 403 Forbidden (imTeamMembershipRequired) wenn du weder Mitglied im Team des Incidents noch Organisations-Admin bist
• 403 Forbidden (imTeamAdminRequired) wenn notify true ist und du weder Team-Admin des Teams noch Organisations-Admin bist
• 400 Bad Request (invalidRequestBody) wenn :id keine positive Ganzzahl ist, role fehlt oder unbekannt ist, oder userId fehlt oder leer ist
• 404 Not Found (imIncidentNotFound) wenn der Incident nicht existiert oder zu einer anderen Organisation gehört
• 422 Unprocessable Entity (invalidUserId) wenn userId nicht existiert oder nicht zu deiner Organisation gehört
• 422 Unprocessable Entity (imIncidentAssigneeNotOnTeam) wenn du nicht Organisations-Admin bist und userId nicht Mitglied im Team des Incidents ist
• 409 Conflict (imIncidentAssignmentExists) wenn die Person diese Rolle im Incident bereits hält