---
title: "Team-Mitglieder"
description: "Mitglieder eines Incident-Management-Teams hinzufügen, einladen, umstufen und entfernen."
---

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](/de/api/incident-management/teams#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`.

## Authentifizierung

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ügen

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

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

### Anfrage (Request Body)

| Feld | Typ | Erforderlich | Beschreibung |
|-------|------|----------|-------------|
| `userId` | string | Ja | Der hinzuzufügende User. Muss zur Organisation des Teams gehören. |
| `imRole` | string | Nein | `admin`, `member` oder `stakeholder`. Standard `member`. |

### Beispiel (cURL)

```bash
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)

`200 OK`

```json
{
  "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 einladen

`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)

| Feld | Typ | Erforderlich | Beschreibung |
|-------|------|----------|-------------|
| `email` | string | Ja | E-Mail-Adresse der Person, die du hinzufügst. |
| `imRole` | string | Nein | `admin`, `member` oder `stakeholder`. Standard `member`. |

### Beispiel (cURL)

```bash
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)

`200 OK`

```json
{
  "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 ändern

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

`:memberId` ist die Mitgliedschafts-ID (`members[].id` aus [Team lesen](/de/api/incident-management/teams#team-lesen)), nicht die User-ID.

### Anfrage (Request Body)

| Feld | Typ | Erforderlich | Beschreibung |
|-------|------|----------|-------------|
| `imRole` | string | Ja | `admin`, `member` oder `stakeholder`. |

### Beispiel (cURL)

```bash
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)

`200 OK`

```json
{ "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 entfernen

`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](/de/api/incident-management/update-schedule) aus den Rotationen, wenn er nicht mehr alarmiert werden soll.

### Beispiel (cURL)

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

### Antwort (Response)

`200 OK`

```json
{ "success": true }
```

## Häufige Fehler

- `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