API-Key Connectivity
The tenant API key lets external systems — CI/CD pipelines, deployment scripts, monitoring jobs or AI clients connecting through MCP — call the msg.ZenTestAI REST API without going through an interactive login. The API key is a long-lived secret bound to one tenant and grants the caller full tenant-administrator access to that tenant's REST endpoints.
Creating and regenerating the API key
The key is managed on the Head-Data tab of Administration → Select your Tenant, in the field msg.ZenTestAI: API-Key.
| Action | What happens |
|---|---|
| Regenerate | Generates a fresh, cryptographically random 64-character key and invalidates the previous one immediately. The newly generated key is shown once in the UI — copy it to a safe place before closing the dialog. msg.ZenTestAI never displays it again. |
| Revoke | Re-generate, then discard the new key. There is no separate "delete" button — regenerating is the only way to invalidate a key. |
Because the previous key is invalidated as soon as you regenerate, plan key rotation during a
maintenance window or stagger your pipelines: any system still using the old key will start to
receive 401 Unauthorized responses immediately.
How to use the key
Send the key in every HTTP request as the zen-test-api-key header:
GET /admin/products HTTP/1.1
Host: zentest.your-domain.com
zen-test-api-key: a3f9b8c1d2e4f6a7b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1
curl example:
curl -H "zen-test-api-key: $ZENTEST_API_KEY" \
https://zentest.your-domain.com/admin/products
The same header works for the MCP endpoint at /mcp.
What the key can access
The key authenticates as a synthetic user that has full tenant-admin rights on exactly one tenant. In practice this means every REST endpoint protected by authentication — and every MCP tool — can be called with the key, as long as the operation stays inside the tenant the key belongs to. This includes:
- Managing test definitions and test sets (create, read, update, delete)
- Triggering and cancelling test executions
- Reading execution results, logs and screenshots
- Managing agents, hosts, macros and external systems
- Reading and (with the appropriate scope) updating tenant settings
Endpoints that are not accessible with an API key:
- Health-check and other unauthenticated probes (which do not need any credentials)
- Internal runner-to-backend communication (uses a separate runner JWT)
How tenant restrictions interact with API-key calls
The API key bypasses login, but it does not bypass any of the tenant restrictions configured on the Restrictions tab. The following limits are enforced regardless of whether the caller used an interactive login, an OIDC token or an API key:
| Restriction | Effect on API-key calls |
|---|---|
| Restrict Tenant to host | URLs that do not match the configured regex are rejected. |
| Max Test-Case Definitions | Test creation calls fail once the limit is reached. |
| Max AI executions per day | Test executions are rejected once the daily quota is reached. |
| Max AI costs per day | Executions are blocked when the daily AI spend is exceeded. |
| Do not allow editing | Mutating calls on existing tests are rejected; reads and new test creations are still allowed (depending on tenant config). |
Properties of the API key
| Property | Behaviour in msg.ZenTestAI |
|---|---|
| Key length / format | 64-character hexadecimal string (256 bits of entropy). |
| Scope | Bound to one tenant. The key has no concept of per-endpoint scopes — it always acts as tenant administrator. |
| Number of active keys | Exactly one per tenant. Regenerating replaces the existing key. |
| Storage at rest | The key is stored encrypted (AES-256-GCM with envelope encryption). Only an indexed cryptographic fingerprint is used for lookups — the plaintext never leaves the secret broker. |
| Audit trail | API-key calls appear in the audit log as a synthetic user api@<tenant>.de. There is no per-key identifier (because there is only one active key at a time). |
Best practices
- Store the key in a secret vault (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, GitHub Actions secrets, GitLab CI variables, …). Never commit it to a Git repository.
- Use separate tenants to isolate environments (e.g. staging vs. production) — each tenant has its own key, so a compromised staging key cannot touch production tests.
- Rotate the key after a personnel change or whenever you suspect it may have leaked.
- When a key is used by MCP clients on a developer machine, prefer the OIDC Bearer flow instead, so each engineer authenticates with their own identity.