Authentifizierung & API-Schlüssel

Pro Plan

Sichern Sie Ihren API-Zugang mit API-Schlüsseln. Erstellen und verwalten Sie Schlüssel für Ihre Integrationen.

Information

Die Zenovay REST API ist ein kostenpflichtiges Feature. Sie benötigen einen Pro-Plan oder höher, um API-Schlüssel zu erstellen und zu verwenden. Kostenlose Teams können weiterhin Ereignisse mit dem Tracking-Skript senden, aber nicht die programmgesteuerte API aufrufen.

Authentifizierungsmethoden

API-Schlüssel (Primär)

Authentifizieren Sie sich über den X-API-Key-Header (empfohlen) oder den Authorization: Bearer-Header:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Oder mit Bearer-Authentifizierung:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

API-Schlüssel beginnen immer mit dem Präfix zv_.

API-Schlüssel erstellen

API-Schlüssel in Zenovay sind persönliche Schlüssel: Jede Anfrage wird Ihnen, dem Benutzer, der den Schlüssel erstellt hat, zugeordnet.

Schritt 1: Öffnen Sie den Bereich für API-Schlüssel

Gehen Sie zu Einstellungen → Konto → Sicherheit & Zugang (/settings/account/security)
Suchen Sie die Karte Persönliche API-Schlüssel
Klicken Sie auf Neuer API-Schlüssel

Seite Einstellungen → Konto → Sicherheit & Zugang mit der Karte Persönliche API-Schlüssel und Button Neuer API-Schlüssel — Auf der Seite Sicherheit & Zugang können Sie Ihre persönlichen API-Schlüssel erstellen und verwalten.

Schritt 2: Konfigurieren Sie den Schlüssel

Das Erstellungsformular erfordert drei Dinge:

┌─────────────────────────────────────────────────────┐
│ API-Schlüssel erstellen                             │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Name des Schlüssels                                 │
│ [ Produktions-Integration                 ]        │
│                                                     │
│ Berechtigungen                                      │
│ ● Vollständiger Zugriff                             │
│ ○ Nur bestimmte Berechtigungen...                   │
│     ☐ Lesen  ☐ Schreiben  ☐ Administrator          │
│                                                     │
│ Team-Zugriff                                        │
│ ● Alle Teams, auf die Sie Zugriff haben             │
│ ○ Nur bestimmte Teams...                            │
│                                                     │
│ [Abbrechen] [Erstellen]                             │
└─────────────────────────────────────────────────────┘

Berechtigungen steuern, was der Schlüssel tun kann. Vollständiger Zugriff erteilt alle Bereiche; oder wählen Sie einzelne Bereiche (Lesen, Schreiben, Administrator). Die External API ist heute schreibgeschützt, daher ist ein Lesen-Schlüssel ausreichend für Analytics.
Team-Zugriff steuert, auf welche Workspaces der Schlüssel zugreifen kann. Lassen Sie ihn bei Alle Teams, auf die Sie Zugriff haben, oder beschränken Sie ihn auf bestimmte Teams.

Schritt 3: Speichern Sie Ihren Schlüssel

Wichtig: Der vollständige Schlüssel wird nur einmal angezeigt. Kopieren Sie ihn, bevor Sie das Dialogfeld schließen.

┌─────────────────────────────────────────────────────┐
│ Ihr neuer API-Schlüssel                             │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Dieser API-Schlüssel wird zukünftig nicht mehr     │
│ sichtbar sein. Bitte kopieren Sie ihn jetzt.        │
│                                                     │
│ zv_abc123xyz789...                                 │
│                                                     │
│ [Kopieren]                                          │
│                                                     │
└─────────────────────────────────────────────────────┘

Schlüsselformat

Alle API-Schlüssel verwenden ein einheitliches Format:

Präfix: zv_
Schlüssel werden als SHA-256-Hashes sicher gespeichert
Der vollständige Schlüssel wird nur einmal bei der Erstellung angezeigt

Es gibt keinen separaten Test-/Sandbox-Schlüsseltyp. Um Entwicklung und Produktion zu trennen, erstellen Sie mehrere Schlüssel mit aussagekräftigen Namen.

Schlüssel-Berechtigungen

Wenn Sie einen Schlüssel erstellen, wählen Sie seine Berechtigungen (Bereiche) und seinen Team-Zugriff.

Bereich	Gewährter Zugriff
Vollständiger Zugriff	Alle Bereiche
Lesen	Schreibgeschützter Zugriff auf die External API
Schreiben	Schreib-Endpunkte (`POST`/`PATCH`/`DELETE`)
Administrator	Nur für Administratoren (`admin` oder `owner` auf dem Team)

Die unten dokumentierte External API ist heute schreibgeschützt, daher benötigen Sie für Analytics einen Lesen-Schlüssel (oder Vollständiger Zugriff). Das Tracking-Ingestion verwendet überhaupt keinen API-Schlüssel; es verwendet das Tracking-Skript.

Auf welche Endpoints API-Schlüssel zugreifen können

Endpoint-Kategorie	Endpoints
Analytics	GET /analytics/:websiteId (Übersicht, Besucher, Seiten, Länder, Technologie)
Websites	GET /websites, GET /websites/:websiteId
Heatmaps	GET /heatmaps/:websiteId/pages
Session Replays	GET /replays/:websiteId/sessions
Error Groups	GET /errors/:websiteId/groups
Usage	GET /usage

Team-Zugriffsbeschränkungen

Alle Teams

Standardmäßig kann ein Schlüssel auf alle Teams (Workspaces) in Ihrem Konto und alle Websites darin zugreifen:

Einfachste Einrichtung
Gut für interne Tools, die über Ihre Workspaces lesen

Ausgewählte Teams

Um einen Schlüssel einzuschränken, wählen Sie Nur bestimmte Teams... und wählen Sie die Teams aus, auf die er zugreifen darf. Der Schlüssel funktioniert dann nur für Websites, die zu diesen Teams gehören.

Anwendungsfälle für Einschränkungen

Szenario	Einstellung
Schlüssel nur für einen Workspace	Nur bestimmte Teams (wählen Sie diesen Team)
Internes Dashboard über alle Ihre Workspaces	Alle Teams, auf die Sie Zugriff haben

Schlüssel verwalten

Alle Schlüssel anzeigen

Die Karte Persönliche API-Schlüssel listet jeden Schlüssel mit seinem Bereich, maskiertem Präfix und letzter Nutzungszeit auf:

┌─────────────────────────────────────────────────────┐
│ Persönliche API-Schlüssel       [+ Neuer API-Schlü]│
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Production    [Vollständiger Zugriff] zv_abc…       │
│ Dashboard     [Lesen]                 zv_def…       │
│ Client A      [Lesen]                 zv_ghi…       │
│                                                     │
└─────────────────────────────────────────────────────┘

Schlüsseldetails

Klicken Sie auf einen Schlüssel, um seine Detailansicht zu öffnen:

Name, Bereich und Team-Zugriff
Erstellungs- und letzte Verwendungs-Zeitstempel
Server-seitige Aktivität (akzeptierte Ereignisanzahlen und aktuelle Ereignisse für diesen Schlüssel)

Schlüssel bearbeiten

Wählen Sie in der Detailansicht aus dem Menü (die Schaltfläche …) die Option Bearbeiten, um den Schlüsselnamen umzubenennen oder seine Bereiche und Team-Zugriff zu ändern, und speichern Sie.

Schlüssel widerrufen

Wenn ein Schlüssel kompromittiert oder nicht verwendet wird:

Öffnen Sie die Detailansicht des Schlüssels
Klicken Sie im Menü … auf Widerrufen
Bestätigen Sie

Der Schlüssel wird sofort ungültig gemacht. Um einen Schlüssel zu ersetzen, widerrufen Sie den alten und erstellen Sie einen neuen.

Schlüsselsicherheit

Best Practices

Praxis	Warum
Verwenden Sie Umgebungsvariablen	Nicht fest im Code einbetten
Erteilen Sie den engsten Bereich und Team-Zugriff	Begrenzen Sie den Auswirkungsradius
Separate Schlüssel pro Integration	Isolieren Sie Dev/Prod und Clients
Widerrufen Sie ungenutzte Schlüssel	Verringern Sie das Risiko
Überwachen Sie die Aktivitätsansicht	Erkennen Sie Anomalien

Umgebungsvariablen

Speichern Sie Schlüssel sicher:

# .env-Datei (niemals einchecken!)
ZENOVAY_API_KEY=zv_abc123...

// Im Code verwenden
const apiKey = process.env.ZENOVAY_API_KEY;

Schlüsselrotation

Zenovay regeneriert keinen Schlüssel an Ort und Stelle. Um zu rotieren:

Erstellen Sie einen neuen Schlüssel
Aktualisieren Sie Ihre Anwendungen, um ihn zu verwenden
Überprüfen Sie, ob alles funktioniert
Widerrufen Sie den alten Schlüssel

API-Schlüssel verwenden

cURL

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
  headers: {
    'X-API-Key': process.env.ZENOVAY_API_KEY,
  }
});

Python

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/websites',
    headers={'X-API-Key': api_key}
)

Fehlerbehebung

Die API gibt Fehler in dieser Form zurück: { "error": { "message": "...", "code": "..." } }.

Fehlender oder ungültiger API-Schlüssel

{
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}

Gibt 401 zurück. Überprüfen Sie:

Der Schlüssel ist korrekt kopiert, mit dem Präfix zv_
Keine zusätzlichen Leerzeichen oder Zeilenumbrüche
Der Schlüssel wurde nicht gelöscht
Sie haben ihn als X-API-Key oder Authorization: Bearer gesendet

Plan schließt keinen API-Zugang ein

{
  "error": {
    "message": "The Zenovay API requires a paid plan. Upgrade to Pro or higher to use API keys.",
    "code": "API_PAID_PLAN_REQUIRED"
  }
}

Gibt 403 zurück. Die External API erfordert einen Pro-Plan oder höher. Upgraden Sie Ihren Workspace, dann erstellen Sie einen Schlüssel.

Für diese Website verboten

{
  "error": {
    "message": "Forbidden",
    "code": "FORBIDDEN"
  }
}

Gibt 403 zurück. Der Schlüssel hat keinen Zugriff auf die angeforderte Website, da die Website zu einem Team außerhalb des Team-Zugriffs des Schlüssels gehört. Verwenden Sie einen Schlüssel, dessen Team-Zugriff diese Website abdeckt, oder erweitern Sie den Team-Zugriff des Schlüssels.

Aktivität & Nutzung

Öffnen Sie die Detailansicht eines Schlüssels, um seine Server-seitige Aktivität zu sehen: akzeptierte Ereignisanzahlen (letzte 24 Stunden, letzte 7 Tage und insgesamt) und die neuesten Ereignisse, die diesem Schlüssel zugeordnet sind. Dies ist nützlich, um zu bestätigen, dass ein Schlüssel live ist, und um unerwartete Nutzung zu erkennen.