Schnittstellen, REST-API, Zugangsschlüssel und Webhooks
Kore hat eine REST-API unter /api/v1. Jede Person erzeugt im Profil persönliche Zugangsschlüssel für ihren Workspace, mit denen Werkzeuge wie n8n, Make oder eigene Skripte Leads lesen, anlegen und ändern. Jede Anfrage läuft als diese Person und unter genau ihren Rechten. Dazu meldet Kore Änderungen an Leads über signierte Webhooks an eigene Adressen. Eine OpenAPI-Beschreibung liegt unter /api/v1/openapi.json.
Wie läuft der Zugriff über die REST-API?
Die REST-API sitzt unter /api/v1, eine maschinenlesbare OpenAPI-Beschreibung liegt unter
/api/v1/openapi.json. Jede Anfrage trägt den Zugangsschlüssel als Bearer-Token. Kore prüft dann Schlüssel,
Mitgliedschaft, Abrechnungssperre und Rolle und führt die Anfrage als die Person aus, der der Schlüssel
gehört. Es gelten dieselben Rechteregeln wie in der App: Was die Person dort nicht sehen darf, bekommt
sie auch über die API nicht.
Die API deckt heute vor allem Leads ab. Als Beispiele:
- Leads lesen und suchen,
- Leads anlegen, mit Quelle und Zusatzfeldern, Dublettenprüfung und einem
Idempotency-Keygegen doppelte Anlage bei Wiederholung, - Kontakt, Phase, Zuweisung und Zusatzfelder eines Leads ändern,
- Notizen anlegen,
- Phasen, Zusatzfelder und Mitglieder lesen.
Die Beispiele zeigen den Zuschnitt, die vollständige und aktuelle Liste steht in der OpenAPI-Beschreibung. Das Anlegen läuft in einer Datenbankfunktion, die App und API gleich benutzen. Dublettenprüfung und Protokoll verhalten sich deshalb an beiden Wegen gleich.
02Wie funktionieren Zugangsschlüssel?
Jede Person erzeugt ihre Schlüssel im Profil unter „Zugangsschlüssel“, je Workspace.
| Eigenschaft | Regelung |
|---|---|
| Stufen | lesen, anlegen, ändern |
| Anzeige | einmal bei der Erzeugung, gespeichert nur als Hash |
| Menge | höchstens 10 Schlüssel je Person |
| Übersicht | „zuletzt benutzt“ je Schlüssel |
| Widerruf | durch die Person selbst oder einen Admin |
Admins sehen unter „API-Verwaltung“ alle Schlüssel des Teams, ohne das Geheimnis. Jede Änderung über einen Schlüssel steht im Verlauf des Leads als „über Schnittstelle“ mit dem Namen des Schlüssels. In der Performance-Auswertung zählt sie als Arbeit der Person, Workflows behandeln sie wie Änderungen von Hand.
03Welche Grenzen setzt Kore?
Damit eine Schnittstelle den Betrieb nicht stört, begrenzt Kore die Last:
- 120 Anfragen pro Minute je Person und 600 pro Minute je Workspace,
- eine Sperre je IP-Adresse für ungültige Schlüssel,
- höchstens 4 gleichzeitige Anfragen,
- 8 Sekunden je Datenbankanweisung.
Wie melden Webhooks Änderungen?
Webhooks drehen die Richtung um: Kore ruft eine eigene Adresse auf, sobald sich an einem Lead etwas ändert. Abonniert werden die elf Ereignistypen, die auch Auslöser der Workflows sind, etwa „Lead angelegt“, „Phase gewechselt“ oder „Termin gebucht“. Die Verwaltung liegt in der API-Verwaltung unter „Webhooks“.
- Signatur: HMAC-SHA256 über Zeitstempel, Ereignis-ID und Inhalt, im Kopf
kore-signatur. Der Empfänger prüft damit, dass die Nachricht von Kore stammt. - Reihenfolge: je Lead mit einer Folgenummer.
- Wiederholung: bis zu 72 Stunden, falls das Ziel nicht antwortet.
- Zustellprotokoll: mit „erneut senden“; liegt schon Neueres vor, fragt Kore vorher zurück.
- Geheimnis erneuern: mit 24 Stunden Überlappung, damit der Empfänger ohne Pause umstellen kann.
- Ausnahmen: einzelne Schlüssel lassen sich ausnehmen, und eine Notbremse stoppt Schleifen.
Ziele sind nur über https auf Port 443 möglich. Kore prüft sie zur Sendezeit gegen interne und private Netze und sendet an genau die geprüfte Adresse. Bei neuem Abo, Adresswechsel und Störung sendet Kore eine Meldung.
05Was geschieht mit Daten beim Löschen?
Löscht oder führt jemand Leads zusammen, schwärzt Kore gespeicherte Webhook-Inhalte und meldet die Löschung jedem Empfänger, der Daten zu diesem Lead erhalten hat.
Häufige Fragen
Zu diesem Bereich. Alle Fragen über alle Bereiche stehen in den häufigen Fragen.
Mit welchen Rechten arbeitet ein Zugangsschlüssel?
Mit denen der Person, der er gehört, und höchstens mit der Stufe, die beim Erzeugen gewählt wurde. Kore prüft bei jeder Anfrage Schlüssel, Mitgliedschaft und Rolle frisch, es gelten dieselben Rechteregeln wie in der App.
Was passiert, wenn jemand das Team verlässt?
Mit dem Austritt und beim Wechsel zur Rolle Partner werden die Schlüssel der Person endgültig widerrufen. Partner bekommen keinen Zugang zur Schnittstelle.
Wie sicher sind die Zugangsschlüssel gespeichert?
Kore zeigt einen Schlüssel nur einmal an und speichert ihn selbst nur als Hash. Ein verlorener Schlüssel lässt sich also nicht wiederherstellen, nur ersetzen.