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/external/user-management/v1/users" \
  -H "Authorization: Bearer sk_meingpt_um_..."

Rate Limiting

Jeder API-Schlüssel hat ein konfigurierbares Rate-Limit (Standard: 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/external/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/external/user-management/v1/users/:userId

Neuen Benutzer erstellen

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

Request-Body:

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

Antwort:

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

Bestehenden Benutzer hinzufügen

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

Request-Body:

{
  "email": "existierend@example.com",
  "sendInviteEmail": true
}

Benutzer entfernen

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

Teams auflisten

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

Antwort:

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

Benutzer zu Team hinzufügen

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

Request-Body:

{
  "userId": "user_123"
}

Benutzer aus Team entfernen

DELETE /api/external/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

Audit-Logging

Alle API-Operationen werden automatisch protokolliert und können von Administratoren eingesehen werden.