---
title: "User Management API"
description: "API zur programmgesteuerten Verwaltung von Benutzern innerhalb einer Organisation"
canonical_url: "https://meingpt.com/docs/api/user-management"
language: de
---

# User Management API

Die User Management API ermöglicht es Partnern und Resellern, Benutzer innerhalb ihrer Organisation programmgesteuert zu verwalten. Diese API ist ideal für automatisierte Benutzerbereitstellung, wenn sich jemand auf einer Partner-Plattform registriert.

## Authentifizierung

Diese API verwendet **Organisation-API-Schlüssel** (nicht Benutzer-API-Schlüssel). Diese Schlüssel werden von Organisationsadministratoren erstellt und haben das Präfix `sk_meingpt_um_`.

```bash
curl -X GET "https://app.meingpt.com/api/user-management/v1/users" \
  -H "Authorization: Bearer $MEINGPT_UM_API_KEY"
```

## Rate Limiting

Alle API-Schlüssel haben ein Rate-Limit von 100 Anfragen/Minute. Die Rate-Limit-Informationen werden in den Response-Headern zurückgegeben:

- `X-RateLimit-Limit`: Maximale Anfragen pro Fenster
- `X-RateLimit-Remaining`: Verbleibende Anfragen
- `X-RateLimit-Reset`: Unix-Zeitstempel, wann das Limit zurückgesetzt wird

## API-Schlüssel erstellen

Organisation-API-Schlüssel können von Administratoren über die Einstellungen erstellt werden. Der Schlüssel wird nur einmal bei der Erstellung angezeigt.

Speicher den API-Schlüssel sicher. Er kann nicht erneut angezeigt werden.

## Endpunkte

### Benutzer auflisten

```
GET /api/user-management/v1/users
```

**Query-Parameter:**
- `page` (optional): Seitennummer (Standard: 1)
- `pageSize` (optional): Benutzer pro Seite (Standard: 20, max: 100)
- `search` (optional): Suche nach E-Mail, Vor- oder Nachname

**Antwort:**
```json
{
  "status": "success",
  "users": [
    {
      "id": "user_123",
      "email": "user@example.com",
      "firstName": "Max",
      "lastName": "Mustermann",
      "createdAt": "2024-01-15T10:30:00Z",
      "lastLogin": "2024-01-20T14:22:00Z",
      "isAdmin": false,
      "teams": [
        { "id": "dept_456", "name": "Marketing" }
      ]
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3
}
```

### Benutzer-Details abrufen

```
GET /api/user-management/v1/users/:userId
```

### Neuen Benutzer erstellen

```
POST /api/user-management/v1/users
```

**Request-Body:**
```json
{
  "email": "neuer.nutzer@example.com",
  "firstName": "Max",
  "lastName": "Mustermann"
}
```

**Antwort:**
```json
{
  "status": "success",
  "user": { ... },
  "isNewUser": true
}
```

Wenn der Benutzer bereits existiert, wird er zur Organisation hinzugefügt und `isNewUser` ist `false`.

### Bestehenden Benutzer hinzufügen

```
POST /api/user-management/v1/users/add
```

**Request-Body:**
```json
{
  "email": "existierend@example.com"
}
```

### Benutzer entfernen

```
DELETE /api/user-management/v1/users/:userId
```

Admin-Benutzer können nicht über die API entfernt werden.

### Benutzerrolle ändern

Schaltet einen Benutzer zwischen **`MEMBER`** (belegt einen Seat/Lizenzplatz) und **`VIEWER`** (Beobachter — kein Seat) um. Ideal, um Nutzer nach Ende eines Programms automatisch auf Beobachter zu setzen (Lizenz wird frei) und bei Wiederaufnahme zurück auf Mitglied.

```
PATCH /api/user-management/v1/users/:userId/role
```

**Request-Body:**
```json
{
  "role": "VIEWER"
}
```

**Antwort:**
```json
{
  "status": "success",
  "user": { ... }
}
```

`VIEWER` (Beobachter) belegt keinen Seat. Beim Umschalten auf `MEMBER` wird
automatisch ein Seat zugewiesen — sind keine Lizenzplätze frei, antwortet die
API mit `412`.

Die Rolle von Admin-Benutzern kann nicht über die API geändert werden. `ADMIN`
ist über die API nicht zuweisbar.

### Teams auflisten

```
GET /api/user-management/v1/teams
```

**Antwort:**
```json
{
  "status": "success",
  "teams": [
    {
      "id": "dept_456",
      "name": "Marketing",
      "isDefault": false,
      "memberCount": 12
    }
  ]
}
```

### Neues Team erstellen

```
POST /api/user-management/v1/teams
```

**Request-Body:**
```json
{
  "name": "Vertrieb"
}
```

**Antwort:**
```json
{
  "status": "success",
  "team": {
    "id": "dept_789",
    "name": "Vertrieb",
    "isDefault": false,
    "memberCount": 0
  }
}
```

Team-Namen müssen innerhalb der Organisation eindeutig sein.

### Team löschen

```
DELETE /api/user-management/v1/teams/:teamId
```

Das Standard-Team kann nicht gelöscht werden. Alle Benutzer werden vor dem Löschen automatisch aus dem Team entfernt.

### Benutzer zu Team hinzufügen

```
POST /api/user-management/v1/teams/:teamId/users
```

**Request-Body:**
```json
{
  "userId": "user_123"
}
```

### Benutzer aus Team entfernen

```
DELETE /api/user-management/v1/teams/:teamId/users/:userId
```

## Fehlerbehandlung

Die API gibt strukturierte Fehlerantworten zurück:

```json
{
  "status": "error",
  "message": "User not found"
}
```

**HTTP-Statuscodes:**
- `400` - Ungültige Eingabe
- `401` - Ungültiger oder fehlender API-Schlüssel
- `403` - Feature nicht aktiviert oder Berechtigungsfehler
- `404` - Ressource nicht gefunden
- `409` - Konflikt (z.B. Benutzer bereits Mitglied)
- `429` - Rate-Limit überschritten
- `500` - Serverfehler