API-Key-Konnektivität
Der Mandanten-API-Key ermöglicht es externen Systemen – wie CI/CD-Pipelines, Deployment-Skripten, Monitoring-Jobs oder KI-Clients, die sich über MCP verbinden –, die msg.ZenTestAI REST-API aufzurufen, ohne sich interaktiv anmelden zu müssen. Der API-Key ist ein langlebiges Geheimnis, das an einen Mandanten gebunden ist und dem Aufrufer vollen Mandantenadministrator-Zugriff auf die REST-Endpunkte dieses Mandanten gewährt.
Erstellen und Neu-Generieren des API-Keys
Der Key wird auf dem Tab Head-Data unter Administration → Mandant auswählen im Feld msg.ZenTestAI: API-Key verwaltet.
| Aktion | Was passiert |
|---|---|
| Neu generieren | Erzeugt einen neuen, kryptografisch zufälligen 64-Zeichen-Key und macht den vorherigen sofort ungültig. Der neu erstellte Key wird einmalig im UI angezeigt – kopieren Sie ihn an einen sicheren Ort, bevor Sie den Dialog schließen. msg.ZenTestAI zeigt ihn danach nie wieder an. |
| Widerrufen | Neu generieren und dann den neuen Key verwerfen. Es gibt keinen separaten "Löschen"-Button – eine Neu-Generierung ist die einzige Möglichkeit, einen Key zu entwerten. |
Da der vorherige Key sofort mit der Neu-Generierung ungültig wird, sollten Sie einen Key-Wechsel (Rotation) während eines Wartungsfensters planen oder Ihre Pipelines zeitlich versetzt aktualisieren: Jedes System, das noch den alten Key verwendet, erhält sofort 401 Unauthorized-Antworten.
Verwendung des Keys
Senden Sie den Key in jedem HTTP-Request als x-zen-test-api-key-Header (der ältere
Header-Name zen-test-api-key wird aus Gründen der Abwärtskompatibilität weiterhin akzeptiert):
GET /admin/products HTTP/1.1
Host: zentest.your-domain.com
x-zen-test-api-key: a3f9b8c1d2e4f6a7b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1
curl-Beispiel:
curl -H "x-zen-test-api-key: $ZENTEST_API_KEY" \
https://zentest.your-domain.com/admin/products
Derselbe Header funktioniert auch für den MCP-Endpunkt unter /mcp.
Zugriffsberechtigungen des Keys
Der Key authentifiziert sich als synthetischer Benutzer, der über volle Mandanten-Admin-Rechte für genau einen Mandanten verfügt. In der Praxis bedeutet dies, dass jeder durch Authentifizierung geschützte REST-Endpunkt – und jedes MCP-Tool – mit diesem Key aufgerufen werden kann, solange sich der Vorgang innerhalb des Mandanten bewegt, zu dem der Key gehört. Dies umfasst:
- Verwalten von Testfällen und Ausführungsplänen (Erstellen, Lesen, Aktualisieren, Löschen)
- Auslösen und Abbrechen von Testausführungen
- Lesen von Ausführungsergebnissen, Logs und Screenshots
- Verwalten von Agenten, Hosts, Makros und externen Systemen
- Lesen und (mit entsprechendem Scope) Aktualisieren von Mandanteneinstellungen
Endpunkte, die nicht mit einem API-Key zugänglich sind:
- Health-Checks und andere nicht authentifizierte Probes (die keine Anmeldedaten benötigen)
- Interne Runner-zu-Backend-Kommunikation (verwendet ein separates Runner-JWT)
Interaktion von Mandanten-Beschränkungen mit API-Key-Aufrufen
Der API-Key umgeht zwar die Anmeldung, jedoch nicht die Mandanten-Beschränkungen, die auf dem Tab Restrictions konfiguriert wurden. Die folgenden Limits werden unabhängig davon durchgesetzt, ob der Aufrufer eine interaktive Anmeldung, ein OIDC-Token oder einen API-Key verwendet hat:
| Beschränkung | Auswirkung auf API-Key-Aufrufe |
|---|---|
| Mandant auf Host beschränken | URLs, die nicht dem konfigurierten Regex entsprechen, werden abgelehnt. |
| Max. Testfall-Definitionen | Aufrufe zur Testerstellung schlagen fehl, sobald das Limit erreicht ist. |
| Max. KI-Ausführungen pro Tag | Testausführungen werden abgelehnt, sobald das Tageskontingent erreicht ist. |
| Max. KI-Kosten pro Tag | Ausführungen werden blockiert, wenn das tägliche KI-Budget überschritten wird. |
| Bearbeitung nicht zulassen | Änderungsaufrufe an bestehenden Tests werden abgelehnt; Lesen und Erstellen neuer Tests sind weiterhin erlaubt (je nach Mandantenkonfiguration). |
Eigenschaften des API-Keys
| Eigenschaft | Verhalten in msg.ZenTestAI |
|---|---|
| Key-Länge / Format | 64-stellige Hexadezimal-Zeichenfolge (256 Bit Entropie). |
| Geltungsbereich (Scope) | Gebunden an einen Mandanten. Der Key kennt keine Endpunkt-spezifischen Scopes – er fungiert immer als Mandantenadministrator. |
| Anzahl aktiver Keys | Genau einer pro Mandant. Eine Neu-Generierung ersetzt den bestehenden Key. |
| Speicherung (At rest) | Der Key wird verschlüsselt gespeichert (AES-256-GCM mit Envelope-Verschlüsselung). Nur ein indizierter kryptografischer Fingerabdruck wird für Suchen verwendet – der Klartext verlässt niemals den Secret-Broker. |
| Audit-Log | API-Key-Aufrufe erscheinen im Audit-Log als synthetischer Benutzer api@<tenant>.de. Es gibt keine Key-spezifische Kennung (da zu jedem Zeitpunkt nur ein aktiver Key existiert). |
Best Practices
- Speichern Sie den Key in einem Secret Vault (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, GitHub Actions Secrets, GitLab CI-Variablen, …). Committen Sie ihn niemals in ein Git-Repository.
- Verwenden Sie separate Mandanten zur Isolierung von Umgebungen (z. B. Staging vs. Produktion) – jeder Mandant hat seinen eigenen Key, sodass ein kompromittierter Staging-Key keinen Zugriff auf Produktionstests hat.
- Rotieren Sie den Key nach einem Personalwechsel oder immer dann, wenn Sie vermuten, dass er in fremde Hände gelangt sein könnte.
- Wenn ein Key von MCP-Clients auf einer Entwicklermaschine verwendet wird, bevorzugen Sie stattdessen den OIDC-Bearer-Flow, damit sich jeder Entwickler mit seiner eigenen Identität authentifiziert.