Authentifizierung
Anfragen werden mit einem geheimen API-Schlüssel authentifiziert, der bei jedem Aufruf als Bearer-Token gesendet wird.
Der Authorization-Header
Senden Sie Ihren API-Schlüssel als Bearer-Token. Sandbox-Schlüssel verwenden das Präfix chsk_test_, Produktionsschlüssel chsk_live_.
curl "https://api.crisphive.com/v1/customers" \ -H "Authorization: Bearer chsk_test_4eC8xQ9mZ2pL7Ka0rT"
Schlüssel verwalten
Erstellen Sie Schlüssel unter Settings → Developers — benennen Sie den Schlüssel, kopieren Sie den Wert einmalig bei der Erstellung, beschränken Sie ihn bei Bedarf auf bestimmte Berechtigungs-Scopes und widerrufen Sie ihn jederzeit.
Ein Schlüssel kann nie mehr tragen als sein Ersteller: Die Scopes eines neuen Schlüssels sind durch die Berechtigungen des erstellenden Nutzers begrenzt, selbst wenn die Scope-Liste leer bleibt. Fordert eine Erstellung mehr an, schlägt sie mit 403 API_KEY_SCOPE_NOT_GRANTED fehl — lassen Sie den Schlüssel von einem Nutzer mit Vollzugriff (oder einem Inhaber) erstellen, wenn Sie die volle Oberfläche benötigen.
Ablauf
API-Schlüssel laufen ab. Sie wählen die Laufzeit eines Schlüssels bei der Erstellung — standardmäßig 30 Tage, von 1 bis 365 — und sie steht für die gesamte Lebensdauer dieses Schlüssels fest. Eine Laufzeit kann später nicht verlängert werden (das Umbenennen eines Schlüssels ändert sie nie), daher verschiebt sich expires_at eines Schlüssels nie. Der Wert wird von der Schlüssel-API zurückgegeben und im Dashboard angezeigt; lesen Sie ihn aus und planen Sie den Wechsel.
Crisphive benachrichtigt außerdem die Inhaber und Administratoren des Unternehmens per E-Mail 7 Tage bevor ein Schlüssel abläuft, und erneut, sobald er abgelaufen ist. Verlassen Sie sich nicht allein auf die E-Mail — sie geht an das Unternehmen, nicht unbedingt an Sie; lesen Sie weiterhin expires_at aus und planen Sie den Wechsel selbst.
Einen Schlüssel erneuern
Zum Erneuern erstellen Sie einen neuen Schlüssel — es gibt keinen Rotate-Endpunkt. Ein Unternehmen kann bis zu 50 aktive Schlüssel pro Umgebung halten, sodass die Übergabe keine besondere Mechanik braucht und ohne Ausfallzeit auskommt:
Erstellen Sie den Ersatzschlüssel im Dashboard.
Stellen Sie den neuen Schlüssel in Ihrer Integration bereit.
Bestätigen Sie, dass der Traffic über den neuen Schlüssel läuft (last_used_at oder Developers → Logs).
Widerrufen Sie den alten Schlüssel im Dashboard.
Das ist dasselbe Zwei-Schlüssel-Verfahren, das AWS für Access Keys dokumentiert. Laden Sie den Schlüssel aus der Konfiguration und hardcoden Sie ihn nie — dann ist Schritt 2 eine Konfigurationsänderung statt eines Releases. Bei einem geleakten Schlüssel gehen Sie in der umgekehrten Reihenfolge vor — widerrufen Sie zuerst, dann erstellen Sie den Ersatz; ein paar fehlgeschlagene Aufrufe sind besser, als einen kompromittierten Schlüssel am Leben zu lassen. Die Schlüsselverwaltung erfolgt ausschließlich über das Dashboard — es gibt keine öffentliche API zum Erstellen oder Widerrufen von Schlüsseln.
401 mit error_code: "API_KEY_EXPIRED" — bewusst getrennt von API_KEY_INVALID (widerrufen, gelöscht oder falsch), damit Ihr Alerting eine versäumte Erneuerung von einem Widerruf unterscheiden kann.Im Namen anderer Unternehmen handeln
API-Schlüssel authentifizieren Ihr eigenes Unternehmen. Sie bauen ein Produkt, mit dem sich andere Crisphive-Unternehmen verbinden? Nutzen Sie stattdessen OAuth 2.1 — jeder Unternehmensinhaber autorisiert Ihre App auf einem Consent-Screen, und es wird nie ein Schlüssel geteilt.