Admin-Oberfläche #

Für die Verwaltung der API-Clients gibt es ein lokales WebView2-Fenster im Look and Feel der übrigen EULANDA-Plugins (EulandaXtrack/EulandaXcel): linke Sidebar, mehrsprachig (de/en), Toast-Meldungen, Hell/Dunkel-Theme.

Show-XrestAdmin -Udl 'C:\Eulanda\Mandant.udl'

Das Fenster braucht Windows PowerShell 5.1 (powershell.exe) - die WebView2-Wrapper von EulandaXtools sind .NET-Framework. Unter pwsh 7 bricht der Aufruf mit einem klaren Hinweis ab; dort die Clients per CLI verwalten (siehe unten). Das Fenster läuft lokal mit den DB-Rechten des Benutzers und braucht keinen API-Key - die Aktionen gehen direkt auf die Datenbank.

Seiten #

Übersicht - Wo bin ich (SQL-Server, Instanz, Datenbank, Anmeldung) und Health-Kacheln: Schema- und Modul-Version, aktive/gesamte Clients, Anfragen und Fehler der letzten 24 Stunden, Zeitpunkt der letzten Anfrage.
Einrichtung - Prüfliste (Verbindung, Rechte, Schema-Stand, offene Migrationen, Administrator), Migration ausführen (bei Bedarf mit stärkerer SQL-Anmeldung), ersten Administrator anlegen.
API-Clients - Liste mit Status und Scopes; Neu/Bearbeiten öffnet einen Editor mit Name, Notiz, Scope-Auswahl (aus dem Katalog), Rolle, Impersonation und den Registry-Präfixen (Lesen/Schreiben). Bei der Neuanlage und der Key-Rotation wird der API-Key einmalig angezeigt.
Benutzer - Anmelde-Benutzer des Mandanten mit Rolle; der letzte aktive Administrator und der eigene Account sind gegen Aussperrung geschützt.
Rollen & Rechte - die Berechtigungs-Matrix (Rollen x Capabilities), identisch zur Ansicht im ERP-Client: ein Haken speichert sofort als Override, Zurücksetzen stellt die Auslieferungs-Vorgaben wieder her.
Geräte - gekoppelte Geräte und Anmeldungen (aus ERP-Client UND Verwaltung); Widerruf nimmt die Anmeldungen des Geräts mit.
Zugriffs-Log - die letzten 200 Anfragen aus xrest.RequestLog (Zeit, Client, Methode, Pfad, Status, Dauer, Fehlercode, IP).

Theme und Sprache wechseln über die Knöpfe unten in der Sidebar; beides wirkt sofort im Fenster (kein Neustart).

Fernwartung über die REST-API #

Dieselben Verwaltungsfunktionen gibt es als REST-Routen - gedacht für den ERP-Client (EulandaXclient), damit ein als administrator angemeldeter Benutzer die üblichen Wartungsarbeiten von unterwegs erledigen kann, ohne im LAN an der Konsole zu sitzen. Maschinennahes bleibt bewusst ohne Route: Migrationen ausführen, TLS-Bindungen, Dienste und die Vergabe der Pairing-PIN gehören auf die Server-Konsole.

Jede Route ist doppelt gegatet: der API-Key braucht den Scope, und die effektiv angemeldete Rolle braucht die settings.*.view-Capability der Route (Default: nur Administrator; zuteilbar über die Berechtigungs-Matrix).

Update-Hinweis für Bestandsinstallationen: ein vorhandener App-Server-Key mit expliziter Scope-Liste kennt die neuen Scopes noch nicht - dem Key api-clients:read, api-clients:write, request-log:read und system:read nachtragen (Set-XrestApiClient -Scope ... ersetzt die Liste komplett, also die bestehenden Scopes mit angeben). Ein Key mit dem Sammel-Scope admin braucht nichts.

Methode und Pfad	Scope	Capability	Zweck
`GET /api/v1/api-clients`	`api-clients:read`	`settings.apiClients.view`	Clients mit Scopes, Rolle, Präfixen, letzter Nutzung (ohne Secrets)
`POST /api/v1/api-clients`	`api-clients:write`	`settings.apiClients.view`	Client anlegen - `apiKey` EINMAL in der Antwort
`PATCH /api/v1/api-clients/{clientId}`	`api-clients:write`	`settings.apiClients.view`	Ändern: `name`, `scopes`, `role`, `canImpersonate`, `enabled`, `notes`, `readPrefixes`, `writePrefixes`
`DELETE /api/v1/api-clients/{clientId}`	`api-clients:write`	`settings.apiClients.view`	Löschen
`POST /api/v1/api-clients/{clientId}/actions/rotate-key`	`api-clients:write`	`settings.apiClients.view`	Key-Rotation - neuer `apiKey` EINMAL in der Antwort
`GET /api/v1/app-sessions`	`app-sessions:manage`	`settings.devices.view`	Gekoppelte Geräte und Anmeldungen
`DELETE /api/v1/app-sessions/{id}`	`app-sessions:manage`	`settings.devices.view`	Sitzung widerrufen; bei einem Gerät fallen dessen Anmeldungen mit
`GET /api/v1/request-log`	`request-log:read`	`settings.requestLog.view`	Zugriffs-Log; Query: `top` (1-1000), `onlyErrors`, `clientId`
`GET /api/v1/system/health`	`system:read`	`settings.system.view`	Server/Instanz/DB, Versionen, Anfragen und Fehler 24h
`GET /api/v1/system/setup`	`system:read`	`settings.system.view`	Einrichtungs-Diagnose (nur lesend)

Selbstschutz gegen Fern-Aussperrung: der API-Key, der den Request authentifiziert (in der Praxis der Key des App-Servers), kann sich selbst nicht deaktivieren, löschen oder rotieren - das beantwortet die API mit 409 CLIENT_SELF_LOCKOUT. Diese Handgriffe gehören auf die Server-Konsole, weil dort auch der neue Key in die Start-Konfiguration eingetragen wird.

Beispiele #

API-Clients auflisten:

$headers = @{ Authorization = "Bearer $apiKey"; 'X-Eul-Login' = 'admin' }
Invoke-RestMethod -Uri 'https://erp.kunde.de/api/v1/api-clients' -Headers $headers |
    Select-Object -ExpandProperty items |
    Format-Table clientId, enabled, role, lastUsedUtc

curl.exe -H "Authorization: Bearer %APIKEY%" -H "X-Eul-Login: admin" ^
    https://erp.kunde.de/api/v1/api-clients

Key eines Fremdsystems rotieren (der neue Key steht genau einmal in der Antwort - danach existiert nur noch der Hash):

$r = Invoke-RestMethod -Method Post -Headers $headers `
    -Uri 'https://erp.kunde.de/api/v1/api-clients/shop/actions/rotate-key'
$r.apiKey   # jetzt sicher beim Verbraucher hinterlegen

curl.exe -X POST -H "Authorization: Bearer %APIKEY%" -H "X-Eul-Login: admin" ^
    https://erp.kunde.de/api/v1/api-clients/shop/actions/rotate-key

Verlorenes Gerät widerrufen (Id aus GET /app-sessions):

Invoke-RestMethod -Method Delete -Headers $headers `
    -Uri 'https://erp.kunde.de/api/v1/app-sessions/17'

curl.exe -X DELETE -H "Authorization: Bearer %APIKEY%" -H "X-Eul-Login: admin" ^
    https://erp.kunde.de/api/v1/app-sessions/17

Nur die Fehler der letzten Zeit ansehen:

Invoke-RestMethod -Headers $headers `
    -Uri 'https://erp.kunde.de/api/v1/request-log?onlyErrors=true&top=50' |
    Select-Object -ExpandProperty items | Format-Table utc, status, path, errorCode

curl.exe -H "Authorization: Bearer %APIKEY%" -H "X-Eul-Login: admin" ^
    "https://erp.kunde.de/api/v1/request-log?onlyErrors=true&top=50"

Wo trägt man einen neuen Key ein? #

Beim Verbraucher des Keys - nach Erst-Erzeugung wie nach Rotation:

App-Server: Parameter -ApiKey von Start-XclientServer bzw. das Feld ApiKey je Mandant in der Mandanten-Konfiguration. Das ist ein Handgriff auf der Server-Maschine - genau deshalb verweigert die API die Rotation des eigenen Keys.
Fremdsysteme (Shop-Anbindung, Postman, Integrationen): in deren Zugangs-Konfiguration.

Fehlercodes #

Code	Status	Bedeutung
`CLIENT_EXISTS`	409	ClientId bereits vergeben
`CLIENT_SELF_LOCKOUT`	409	Der eigene Key kann sich nicht deaktivieren, löschen oder rotieren
`FORBIDDEN_CAPABILITY`	403	Der effektiven Rolle fehlt die `settings.*.view`-Capability
`FORBIDDEN_SCOPE`	403	Dem API-Key fehlt der Scope der Route
`ROLE_UNKNOWN`	422	Unbekannte Rolle beim Anlegen/Ändern
`NOT_FOUND`	404	ClientId bzw. Sitzungs-Id existiert nicht

Verwaltung per CLI (pwsh 7 und Automatisierung) #

Dieselben Aktionen ohne Fenster:

# Anlegen (Key wird einmalig zurückgegeben)
New-XrestApiClient -Udl $udl -ClientId 'shop' -Name 'Shop' `
    -Scope 'addresses:read', 'articles:read'

# Ändern: Scopes und Registry-Präfixe ersetzen, aktivieren/deaktivieren
Set-XrestApiClient -Udl $udl -ClientId 'shop' -Enabled:$false
Set-XrestApiClient -Udl $udl -ClientId 'shop' `
    -Scope 'addresses:read', 'articles:read', 'registry:read' `
    -RegistryReadPrefix '\VENDOR\esol\MODULES\DMS'

# Anzeigen und löschen
Get-XrestApiClient -Udl $udl | Format-Table ClientId, Enabled, Scopes
Remove-XrestApiClient -Udl $udl -ClientId 'shop'

Der API-Key ist nie auslesbar (nur als Hash gespeichert). Bei Kompromittierung den Client löschen oder deaktivieren und neu anlegen.