API-Key-Konnektivität
Der Tenant-API-Key ermöglicht externen Systemen – CI/CD-Pipelines, Deployment-Skripten, Monitoring-Jobs oder KI-Clients, die sich über MCP verbinden –, die msg.ZenTestAI REST-API aufzurufen, ohne einen interaktiven Login durchzuführen. Der API-Key ist ein langlebiges Geheimnis, das an einen Tenant gebunden ist und dem Aufrufer volle Tenant-Administratorrechte für die REST-Endpunkte dieses Tenants gewährt.
Erstellen und Neu-Generieren des API-Keys
Der Key wird auf dem Tab Head-Data (./tenantSettings#head-data) unter Administration → Wählen Sie Ihren Tenant im Feld msg.ZenTestAI: API-Key verwaltet.
| Aktion | Was passiert |
|---|---|
| Regenerate | Erzeugt einen neuen, kryptografisch zufälligen 64-Zeichen-Key und macht den vorherigen sofort ungültig. Der neu generierte Key wird einmalig in der UI angezeigt – kopieren Sie ihn an einen sicheren Ort, bevor Sie den Dialog schließen. msg.ZenTestAI zeigt ihn nie wieder an. |
| Revoke | Neu generieren und dann den neuen Key verwerfen. Es gibt keinen separaten "Löschen"-Button – eine Neu-Generierung ist der einzige Weg, einen Key ungültig zu machen. |
Da der vorherige Key sofort mit der Neu-Generierung ungültig wird, planen Sie die Rotation des Keys während eines Wartungsfensters oder staffeln Sie Ihre Pipelines: Jedes System, das noch den alten Key verwendet, erhält sofort 401 Unauthorized-Antworten.
Verwendung des Keys
Senden Sie den Key in jeder HTTP-Anfrage als zen-test-api-key Header:
GET /admin/products HTTP/1.1
Host: zentest.your-domain.com
zen-test-api-key: a3f9b8c1d2e4f6a7b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1
curl-Beispiel:
curl -H "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.
Was der Key aufrufen kann
Der Key authentifiziert sich als synthetischer Benutzer, der über volle Tenant-Admin-Rechte für genau einen Tenant verfügt. In der Praxis bedeutet dies, dass jeder durch Authentifizierung geschützte REST-Endpunkt – und jedes MCP-Tool – mit dem Key aufgerufen werden kann, solange sich der Vorgang innerhalb des Tenants bewegt, zu dem der Key gehört. Dies umfasst:
- Verwalten von Testdefinitionen und Test-Sets (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 Tenant-Einstellungen
Endpunkte, die nicht mit einem API-Key zugänglich sind:
- Health-Check und andere nicht authentifizierte Probes (die keine Zugangsdaten benötigen)
- Interne Runner-zu-Backend-Kommunikation (verwendet ein separates Runner-JWT)
Wechselwirkung zwischen Tenant-Beschränkungen und API-Key-Aufrufen
Der API-Key umgeht den Login, aber er umgeht nicht die auf dem Tab Restrictions konfigurierten Tenant-Beschränkungen. Die folgenden Limits werden unabhängig davon durchgesetzt, ob der Aufrufer einen interaktiven Login, ein OIDC-Token oder einen API-Key verwendet hat:
| Beschränkung | Auswirkung auf API-Key-Aufrufe |
|---|---|
| Restrict Tenant to host | URLs, die nicht dem konfigurierten Regex entsprechen, werden abgelehnt. |
| Max Test-Case Definitions | Test-Erstellungsaufrufe schlagen fehl, sobald das Limit erreicht ist. |
| Max AI executions per day | Testausführungen werden abgelehnt, sobald das tägliche Kontingent erreicht ist. |
| Max AI costs per day | Ausführungen werden blockiert, wenn das tägliche KI-Budget überschritten wird. |
| Do not allow editing | Mutierende Aufrufe an bestehenden Tests werden abgelehnt; Lesen und Erstellen neuer Tests sind weiterhin erlaubt (je nach Tenant-Konfiguration). |
Eigenschaften des API-Keys
| Eigenschaft | Verhalten in msg.ZenTestAI |
|---|---|
| Key-Länge / Format | 64-stellige Hexadezimal-Zeichenkette (256 Bits Entropie). |
| Scope | An einen Tenant gebunden. Der Key hat kein Konzept von pro-Endpunkt-Scopes – er agiert immer als Tenant-Administrator. |
| Anzahl aktiver Keys | Genau einer pro Tenant. Eine Neu-Generierung ersetzt den vorhandenen Key. |
| Speicherung | Der Key wird verschlüsselt gespeichert (AES-256-GCM mit Envelope-Verschlüsselung). Nur ein indizierter kryptografischer Fingerabdruck wird für Lookups verwendet – der Klartext verlässt nie den Secret Broker. |
| Audit-Log | API-Key-Aufrufe erscheinen im Audit-Log als synthetischer Benutzer api@<tenant>.de. Es gibt keine pro-Key-Identifizierung (da es zu jedem Zeitpunkt nur einen aktiven Key gibt). |
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 Tenants, um Umgebungen zu isolieren (z. B. Staging vs. Produktion) – jeder Tenant hat seinen eigenen Key, sodass ein kompromittierter Staging-Key keine Produktionstests beeinflussen kann.
- Rotieren Sie den Key nach einem Personalwechsel oder wann immer Sie vermuten, dass er geleakt sein könnte.
- Wenn ein Key von MCP-Clients auf einer Entwickler-Maschine verwendet wird, bevorzugen Sie stattdessen den OIDC-Bearer-Flow, damit sich jeder Entwickler mit seiner eigenen Identität authentifiziert.