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_.

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.

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:

{
  "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:

{
  "email": "neuer.nutzer@example.com",
  "firstName": "Max",
  "lastName": "Mustermann"
}

Antwort:

{
  "status": "success",
  "user": { ... },
  "isNewUser": true
}

Bestehenden Benutzer hinzufügen

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

Request-Body:

{
  "email": "existierend@example.com"
}

Benutzer entfernen

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

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:

{
  "role": "VIEWER"
}

Antwort:

{
  "status": "success",
  "user": { ... }
}

Teams auflisten

GET /api/user-management/v1/teams

Antwort:

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

Neues Team erstellen

POST /api/user-management/v1/teams

Request-Body:

{
  "name": "Vertrieb"
}

Antwort:

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

Team löschen

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

Benutzer zu Team hinzufügen

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

Request-Body:

{
  "userId": "user_123"
}

Benutzer aus Team entfernen

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

Fehlerbehandlung

Die API gibt strukturierte Fehlerantworten zurück:

{
  "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