Team-Mitglieder

Die Mitgliedschaft entscheidet, wer in die Rotationen und Overrides eines Teams aufgenommen werden kann, und wer Team-Admin (imRole: "admin") mit Schreibrecht auf genau dieses Team ist. Die aktuellen Mitglieder liest du mit Team lesen.

Mitgliederrollen (imRole): admin, member oder stakeholder. Standard ist member.

Mitglied werden kann nur, wer Incident Management selbst nutzen dürfte: aktive User mit der Organisationsrolle admin, editor oder responder.

AuthentifizierungAnkerlink kopieren

Basis-IM-Zugriff (eine IM-berechtigte Rolle oder ein organisationsweiter API-Token, Incident Management aktiviert) plus die Team-Schreibhürde: Organisationsrolle admin, oder Team-Admin dieses Teams. Ein API-Token läuft mit der Rolle des Users, der ihn erstellt hat, also kommt nur ein Token durch, den ein Organisations-Admin erstellt hat. Ein neues User-Konto über die Einladung anzulegen braucht zusätzlich die Organisationsrolle admin.

Mitglied hinzufügenAnkerlink kopieren

POST /api/im/teams/:id/members

Fügt einen bestehenden User deiner Organisation zum Team hinzu.

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/teams/3/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "u_def456", "imRole": "member" }'

Antwort (Response)Ankerlink kopieren

200 OK

{
  "id": 18,
  "userId": "u_def456",
  "imRole": "member",
  "user": { "name": "Bob Fixit", "email": "bob@example.com" }
}

id ist die Mitgliedschafts-ID, die die Endpunkte unten verwenden. user.email ist null, außer du bist Organisations-Admin.

Mitglied per E-Mail einladenAnkerlink kopieren

POST /api/im/teams/:id/invite

Fügt ein Mitglied über die E-Mail-Adresse statt über die User-ID hinzu:

• Die E-Mail gehört zu einem User deiner Organisation: Dieser User wird mit dem Team verknüpft. Sein Konto und seine Rolle bleiben unberührt, es geht keine E-Mail raus.
• Zur E-Mail gibt es kein Konto: Ein neuer User mit der Organisationsrolle responder wird angelegt, mit dem Team verknüpft und bekommt eine Einladungs-E-Mail. Braucht die Organisationsrolle admin.
• Die E-Mail gehört zu einem Konto in einer anderen Organisation: Abgelehnt mit 422, es wird nichts angelegt.

Die E-Mail wird ohne Beachtung der Groß-/Kleinschreibung abgeglichen und klein gespeichert.

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/teams/3/invite" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "carla@example.com" }'

Antwort (Response)Ankerlink kopieren

200 OK

{
  "id": 19,
  "userId": "u_ghi789",
  "imRole": "member",
  "invitedNewUser": true,
  "user": { "name": "carla@example.com", "email": "carla@example.com" }
}

invitedNewUser ist true, wenn ein neues Konto angelegt wurde und die Einladungs-E-Mail rausging. Bis sich die Person anmeldet, ist ihr name ihre E-Mail-Adresse.

Rolle eines Mitglieds ändernAnkerlink kopieren

PATCH /api/im/teams/:id/members/:memberId

:memberId ist die Mitgliedschafts-ID (members[].id aus Team lesen), nicht die User-ID.

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X PATCH "$BASE_URL/api/im/teams/3/members/18" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "imRole": "admin" }'

Antwort (Response)Ankerlink kopieren

200 OK

{ "id": 18, "userId": "u_def456", "imRole": "admin" }

Sendest du die Rolle, die das Mitglied schon hat, kommt dieselbe Form zurück und nichts ändert sich.

Mitglied entfernenAnkerlink kopieren

DELETE /api/im/teams/:id/members/:memberId

Entfernt die Mitgliedschaft. Der User bleibt in allen Rotationsgruppen der Team-Schedules und behält seine Overrides; nimm ihn mit Schedule aktualisieren aus den Rotationen, wenn er nicht mehr alarmiert werden soll.

Beispiel (cURL)Ankerlink kopieren

curl -X DELETE "$BASE_URL/api/im/teams/3/members/18" \
  -H "Authorization: Bearer $TOKEN"

Antwort (Response)Ankerlink kopieren

200 OK

{ "success": true }

Häufige FehlerAnkerlink kopieren

• 401 Unauthorized (unauthorized) wenn du nicht authentifiziert bist
• 403 Forbidden (imAccessDenied) bei einem kunden-gescopten Token, oder wenn deine Session keine IM-berechtigte Rolle hat
• 403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
• 403 Forbidden (imTeamWriteDenied) wenn du weder Organisations-Admin noch Team-Admin dieses Teams bist
• 403 Forbidden (forbidden) bei der Einladung, wenn es zur E-Mail noch kein Konto gibt und du kein Organisations-Admin bist
• 404 Not Found (imTeamNotFound) wenn das Team nicht existiert oder zu einer anderen Organisation gehört
• 404 Not Found (imTeamMemberNotFound) wenn :memberId keine Mitgliedschaft dieses Teams ist
• 404 Not Found (userNotFound) wenn userId nicht existiert oder zu einer anderen Organisation gehört
• 400 Bad Request (invalidRequestBody) wenn :id oder :memberId keine positive Ganzzahl ist, userId fehlt, email fehlt oder keine E-Mail-Adresse ist, oder imRole nicht admin, member oder stakeholder ist
• 400 Bad Request (imUserNotEligible) wenn der User inaktiv ist oder nicht die Organisationsrolle admin, editor oder responder hat
• 422 Unprocessable Entity (imInviteEmailNotEligible) wenn die E-Mail zu einem Konto in einer anderen Organisation gehört
• 409 Conflict (imTeamMemberExists) wenn der User schon Mitglied dieses Teams ist