Die REST-API von Zenovay ist auf docs.zenovay.com dokumentiert. Jede Anfrage authentifiziert sich mit einem Bearer-Token (einem „API-Schlüssel"), den Sie im Dashboard generieren.
Information
Die REST-API ist eine kostenpflichtige Funktion. Sie ist in den Plänen Pro, Scale und Enterprise verfügbar. Im kostenlosen Plan können Sie keine API-Schlüssel erstellen oder verwenden. Führen Sie ein Upgrade über Einstellungen → Abrechnung durch, um die Funktion freizuschalten.
Wie API-Schlüssel organisiert sind
Zenovay-Schlüssel sind persönlich: Jeder Schlüssel wird von Ihnen erstellt und fungiert in Ihrem Namen für die Teams (Arbeitsbereiche), denen Sie ihm Zugriff gewähren. Sie verwalten sie in Ihrem Konto und werden automatisch widerrufen, wenn Sie den Zugriff auf ein Team verlieren.
Beim Erstellen eines Schlüssels entscheiden Sie zwei Dinge:
- Welche Berechtigungen er hat — vollständiger Zugriff oder eine beliebige Kombination aus Lesen, Schreiben und Admin.
- Welche Teams er erreichen kann — alle Teams, denen Sie angehören, oder eine bestimmte Teilmenge.
Arbeitsbereich-Besitzer und Administratoren können entscheiden, wer API-Schlüssel erstellen darf, die den Arbeitsbereich erreichen (alle Mitglieder, nur Besitzer und Administratoren oder niemand). Diese Governance befindet sich auf der Arbeitsbereich-API-Seite unter Einstellungen → Sicherheit & Zugriff → API-Schlüssel.
Einen API-Schlüssel generieren
Öffnen Sie Ihre Kontoeinstellungen für Sicherheit
Gehen Sie in
app.zenovay.comzu Einstellungen → Konto → Sicherheit & Zugriff, dann suchen Sie die Karte API-Schlüssel.Erstellen Sie einen neuen Schlüssel
Klicken Sie auf API-Schlüssel erstellen und geben Sie einen Namen ein, der die Integration beschreibt (z. B.
Slack-Alerts,Interner Datenexport). Namen können bis zu 64 Zeichen lang sein.Wählen Sie die Berechtigungen
- Vollständiger Zugriff — Lesen und Schreiben auf alles, was der Schlüssel erreichen kann.
- Auswählen — wählen Sie eine beliebige Kombination aus Lesen (GET-Analytics-Endpunkte), Schreiben (POST/PATCH/DELETE) und Admin (Admin-Only-Endpunkte). Diese sind unabhängig: Ein Schlüssel nur zum Lesen, ein Webhook-Receiver nur zum Schreiben und ein Automatisierungsschlüssel nur für Admin sind alle gültig.
Der Bereich Admin kann nur Teams als Ziel haben, bei denen Sie Besitzer oder Admin sind.
Wählen Sie den Team-Zugriff
- Alle Teams — der Schlüssel funktioniert für alle Teams, denen Sie derzeit angehören.
- Teams auswählen — sperren Sie den Schlüssel auf bestimmte Teams. Ideal zum Begrenzen eines Schlüssels auf einen Arbeitsbereich.
Kopieren Sie den Schlüssel einmalig
Der Schlüssel beginnt mit
zv_und wird nur einmal zum Erstellungszeitpunkt angezeigt. Kopieren Sie ihn sofort in Ihren Secrets-Manager. Wir speichern nur einen Hash, daher können wir einen verlorenen Schlüssel nicht wiederherstellen.
Hello-World-Anfrage
Jeder API-Aufruf sendet den Schlüssel als Bearer-Token im Header Authorization.
curl https://api.zenovay.com/api/external/v1/websites \
-H "Authorization: Bearer zv_your_actual_key_here"
Eine erfolgreiche Antwort gibt die Websites, auf die der Schlüssel Zugriff hat, als JSON zurück. Wenn der Schlüssel ungültig oder widerrufen ist, erhalten Sie 401 Unauthorized. Wenn Ihr Plan keinen API-Zugriff enthält, erhalten Sie 403.
Rate-Limits
API-Anfragen sind pro Plan begrenzt:
| Plan | Anfragen pro Minute |
|---|---|
| Free | Kein API-Zugriff |
| Pro | 30 |
| Scale | 60 |
| Enterprise | 120 |
Antworten enthalten die Header X-RateLimit-Limit und X-RateLimit-Remaining, sodass Sie sie lesen und drosseln können, wenn Sie sich dem Limit nähern. Unter API-Rate-Limits finden Sie weitere Informationen.
Schlüssel widerrufen
- Widerrufen — öffnen Sie den Schlüssel unter Einstellungen → Konto → Sicherheit & Zugriff, dann wählen Sie Widerrufen. Der Schlüssel funktioniert sofort nicht mehr.
- Bearbeiten — Sie können einen Schlüssel umbenennen oder seine Berechtigungen und seinen Team-Zugriff von derselben Stelle aus anpassen.
- Audit — jeder Schlüssel zeigt, wann er erstellt wurde. Wenn Sie einen Schlüssel nicht erkennen oder die dahinterliegende Integration nicht mehr verwenden, widerrufen Sie ihn.
Um einen Schlüssel zu rotieren, erstellen Sie einen neuen, stellen ihn bereit und widerrufen Sie dann den alten.
MCP-Server
Zenovay spricht auch das Model Context Protocol, sodass Sie Claude Desktop, Cursor oder jeden beliebigen MCP-Client direkt mit Ihrer Analytics verbinden können. MCP ist in allen Plänen verfügbar (Free, Pro, Scale und Enterprise) mit täglichen Abfragelimits pro Plan. Es verwendet keine REST-API-Schlüssel — stattdessen verbinden Sie Ihren Client mit https://api.zenovay.com/mcp und autorisieren ihn einmalig über OAuth (kein zu kopierender Schlüssel). Sie können verbundene MCP-Clients unter Einstellungen → Konto → Sicherheit & Zugriff überprüfen und widerrufen. Unter MCP-Dokumentation auf der Entwickler-Website finden Sie die vollständige Einrichtung und Werkzeugliste.
Best Practices
- Committen Sie einen Schlüssel niemals in ein öffentliches Repo. Speichern Sie Schlüssel in einem Secrets-Manager, nicht in der Versionskontrolle.
- Ein Schlüssel pro Integration. Wenn ein Anbieter kompromittiert wird, widerrufen Sie nur seinen Schlüssel.
- Verwenden Sie die engsten Berechtigungen, die die Integration benötigt. Verwenden Sie nur Lesen, es sei denn, es muss schreiben.
- Begrenzen Sie pro Team für Integrationen, die nur einen Arbeitsbereich berühren, sodass ein durchgesickerter Schlüssel nicht den Rest erreichen kann.