API-Schlüssel
Mit einem API-Schlüssel kann Ihre Website, Ihre App oder Ihr Server ohne Anmeldung in der Oberfläche mit dem Projekt arbeiten: Ereignisse senden, Profile lesen, Segmente, Journeys und Kampagnen verwalten. Schlüssel erstellen und widerrufen Sie unter „Einstellungen“ → „API-Schlüssel“.
Der Bereich ist für „Inhaber“, „Administrator“ und „Manager“ sichtbar. Schlüssel erstellen und widerrufen können „Inhaber“ und „Administrator“.
Schlüsseltypen
| Write | Secret | |
|---|---|---|
| Beginnt mit | cdp_wk_ |
cdp_sk_ |
| Erlaubt | nur das Senden von Ereignissen | das Senden von Ereignissen und Aktionen im Projekt gemäß den gewählten Berechtigungen |
| Einsatzort | Website-Code, mobile App, Server | nur Ihr Server |
| Darf öffentlich sein | ja, er ist im Code der Website-Seiten sichtbar | nein, halten Sie ihn geheim |
| Anfragelimit | 6000 pro Minute | 1200 pro Minute (Standard) |
Der Write-Schlüssel ist von Natur aus öffentlich: Er steht im Code jeder Seite Ihrer Website. Mit ihm lassen sich nur Ereignisse senden, ein Leck gibt also keinen Zugriff auf Daten frei. Damit keine fremde Website in Ihrem Namen Ereignisse sendet, können Sie im Bereich „Website“ die Domains festlegen, von denen der Schlüssel angenommen wird – siehe Website anbinden.
Der Secret-Schlüssel gewährt serverseitigen Zugriff auf die Projektdaten. Fügen Sie ihn niemals in Seitencode, mobile Apps oder öffentliche Repositorys ein.
Schlüssel erstellen
- Öffnen Sie „API-Schlüssel“.
- Geben Sie in der Karte „Neuer Schlüssel“ einen „Name“ ein – daran erkennen Sie später, wo der Schlüssel verwendet wird, zum Beispiel „Website“ oder „Onlineshop-Server“.
- Wählen Sie den „Typ“: „Schreiben“ (Write) oder „Geheim“ (Secret).
- Markieren Sie bei Secret die „Schlüsselberechtigungen“ – nur das, was die Integration tatsächlich braucht.
- Klicken Sie auf „Schlüssel erstellen“.
Direkt nach dem Erstellen erscheint oben auf der Seite der vollständige Schlüssel. Klicken Sie auf „Kopieren“ und speichern Sie ihn, etwa in einem Passwort-Manager oder in den Umgebungsvariablen des Servers. Ein geheimer Schlüssel wird nur einmal angezeigt: Wir speichern nur seinen Fingerabdruck, wiederherstellen lässt er sich nicht. Haben Sie ihn verloren, erstellen Sie einen neuen und widerrufen Sie den alten.
Einen Write-Schlüssel für die Website erstellen Sie am bequemsten direkt im Bereich „Website“: Dort wird er sofort in den Installationscode eingesetzt und ist jederzeit abrufbar – siehe Website anbinden.
Die Schlüsseltabelle zeigt Name, wer ihn wann erstellt hat, Typ, den Anfang des Schlüssels (zum Beispiel cdp_sk_a1b2…), die Anzahl der Berechtigungen und den Zeitpunkt der letzten Verwendung.
Berechtigungen geheimer Schlüssel
Sie können einem Schlüssel nur Berechtigungen geben, die Sie selbst haben. Die Berechtigungen gelten für das gesamte Projekt – einen Schlüssel auf einzelne Journeys oder Segmente zu beschränken, ist nicht möglich.
| Berechtigung | Was sie freigibt |
|---|---|
| Profile lesen | Profil anhand der Kennung und seine Ereignisse |
| Personenbezogene Daten unmaskiert | E-Mail, Telefonnummer und andere persönliche Daten im Klartext; ohne diese Berechtigung werden sie maskiert |
| Profile und Einwilligungen ändern | Einwilligungen für Kampagnen, Telegram-Verknüpfung |
| Profile löschen (DSGVO) | Löschen eines Profils auf Wunsch des Kunden |
| Ereignis- und Merkmalskatalog | Liste der Ereignisse und Profilmerkmale |
| Segmente lesen / Segmente ändern | Anzeigen, Erstellen, Ändern, Löschen und Neuberechnen von Segmenten |
| Journeys und Berichte lesen; Entwürfe bearbeiten und Teilnehmer aufnehmen; Journeys veröffentlichen, pausieren und archivieren | Arbeit mit Journeys |
| Kampagnen und Berichte lesen; Kampagnen erstellen und bearbeiten; Kampagnen starten, pausieren und abbrechen | Arbeit mit Kampagnen |
| Produktkatalog und Empfehlungen lesen; Produkte hochladen und löschen | Produkte und Empfehlungen |
| Analysen | Berichte |
Beispiel: Ein Schlüssel zur Synchronisierung von VIP-Kunden aus dem CRM benötigt nur die Berechtigungen „Segmente lesen“ und „Segmente ändern“.
Alle über einen geheimen Schlüssel ausgeführten Aktionen werden im Audit-Log des Projekts im Namen des Schlüssels erfasst – siehe Projekteinstellungen, Tarif und Audit.
Schlüssel widerrufen
- Suchen Sie den Schlüssel in der Tabelle und klicken Sie auf „Widerrufen“.
- Bestätigen Sie die Aktion.
Anfragen mit diesem Schlüssel funktionieren sofort nicht mehr (Antwort 401). Der widerrufene Schlüssel bleibt mit dem Vermerk „Widerrufen“ in der Liste, damit seine Historie sichtbar ist. Wiederherstellen lässt er sich nicht – erstellen Sie bei Bedarf einen neuen.
Widerrufen Sie einen Schlüssel sofort, wenn Unbefugte ihn erhalten haben könnten, wenn eine Person mit Zugriff darauf das Unternehmen verlassen hat oder wenn die Integration nicht mehr genutzt wird.
Wichtig zu wissen
- Limits. Wird das Anfragelimit oder das monatliche Ereigniskontingent des Tarifs überschritten, antwortet die API mit
429. Verteilen Sie den Versand gleichmäßig und wiederholen Sie die Anfrage nach einer Pause. - Schlüssel sicher austauschen. Erstellen Sie einen neuen Schlüssel, hinterlegen Sie ihn auf dem Server, prüfen Sie, dass Anfragen ankommen (Feld „Zuletzt verwendet“), und widerrufen Sie erst dann den alten.
- Ein eigener Schlüssel pro Integration. So ist im Audit-Log erkennbar, wer was getan hat, und bei einem Leck genügt es, einen einzigen Schlüssel zu widerrufen.
- Wie Sie Ereignisse senden und die API vom Server aufrufen, lesen Sie im Artikel Serverseitige Integration.