Ein API-Schlüssel ist ein Passwort für ein Programm. Wer ihn besitzt, kann alles tun, was der Schlüssel darf, von überall, wo der Schlüssel akzeptiert wird, bis er abläuft. Diese Seite zeigt, wie man den Schaden durch einen abgeflossenen Schlüssel klein hält. Wie Schlüssel erstellt werden und die API aufgerufen wird, steht unter Authentifizierung.
Schlüssel werden unter API Keys im Bereich Developer des Menüs verwaltet (Admin; zum Rotieren wird die Rolle Owner benötigt).
Was ein Schlüssel niemals darf
Diese Grenzen gelten für jeden Schlüssel, unabhängig davon, was Sie anhaken:
- Ein Schlüssel geht nie über das hinaus, was das Mitglied, das ihn erstellt hat, jetzt darf: „Er geht nie über das hinaus, was sein Eigentümer jetzt darf.“ Verliert das Mitglied eine Berechtigung, verliert der Schlüssel sie ebenfalls.
- Ein Schlüssel hat nie Berechtigungen, die nur dem Owner vorbehalten sind, und nie Berechtigungen der Identitäts- und Zugriffsmodule (Anmeldung, Konten, API-Schlüssel). Daher kann ein Schlüssel keine Schlüssel erstellen oder rotieren und keine Mitglieder ändern.
- Die Berechtigung eines Schlüssels wirkt nur, solange ihr Modul für Ihre Organisation aktiviert ist.
- Eine Anfrage, die einen Schlüssel mitführt, wird ausschließlich als dieser Schlüssel beurteilt; ein Browser-Cookie in derselben Anfrage wird ignoriert.
1. Nur die nötigen Berechtigungen vergeben
Wählen Sie unter New API Key die Module permissions jeweils für ein Modul aus. Jedes Modul bietet eine Voreinstellung Read only. Typische Integrationen:
| Integration | Berechtigungen |
|---|---|
| Ein Berichtswerkzeug, das Geräte und Verlauf liest | Read only auf Geräte und Telemetrie |
| Ein ERP, das Grenzwerte auf Geräte schreibt | Geräte lesen, Attribute schreiben |
| Ein Ticketsystem, das Alarme bestätigt | Alarme lesen, bestätigen |
Vermeiden Sie einen Schlüssel für alles. Ein Schlüssel pro Integration macht klar, was ein Abfluss offenlegt, und erlaubt es, eine Integration zu sperren, ohne die anderen zu stoppen.
Integrationsbereiche (Read, Write, Admin, SCIM Read, SCIM Write) sind für Maschinen-Endpunkte mit eigenem Vertrag gedacht, etwa die SCIM-Bereitstellung. „Die oben genannten Modulberechtigungen brauchen die meisten Integrationen.“
2. Schlüssel an Netzwerke binden
IP allowlist (optional): „Ein Subnetz pro Zeile, z. B. 10.0.0.0/8 oder 203.0.113.7/32.“ Aufrufe von anderswo werden mit derselben Antwort abgelehnt wie ein unbekannter Schlüssel, sodass ein Angreifer nichts erfährt.
Ihre Organisation kann einen Standard für Schlüssel ohne eigene Liste festlegen: API Key Settings > Tenant Subnet Allowlist.
3. Schlüssel ablaufen lassen
Jeder Schlüssel läuft ab: standardmäßig nach 90 Tagen, höchstens nach 365 Tagen („Standardmäßig 90 Tage, höchstens ein Jahr.“). Unter API Key Settings:
| Einstellung | Standard | Verwendung |
|---|---|---|
| Maximum Key Lifetime (days) | 0 (die Obergrenze von 365 Tagen) | Senken Sie den Wert, um kürzere Laufzeiten zu erzwingen. Dadurch sinkt auch der Standard. |
| Require Expiry on Every Key | Aus | API-Aufrufe, die Schlüssel erstellen, müssen ein Ablaufdatum angeben. |
| Max Active Keys | 0 (unbegrenzt) | Begrenzt, wie viele Schlüssel gleichzeitig aktiv sein können. |
| Per-Key Rate Limit (requests/minute) | 0 (der Plattform-Standard: 1.000 pro Minute) | Standard-Anfragelimit jedes Schlüssels. Die Anzeige nennt 0 unbegrenzt; die Plattform wendet 1.000 pro Minute an. |
4. Den Besitz des Schlüssels festlegen
Ein Schlüssel hört auf zu funktionieren, wenn das Mitglied, das ihn erstellt hat, die Organisation verlässt, es sei denn, er ist als Service key markiert („Ja: überlebt seinen Ersteller“). Markieren Sie Schlüssel von Produktivintegrationen als Service-Schlüssel und notieren Sie, wer für jeden verantwortlich ist.
5. Regelmäßig rotieren
Rotate key erstellt einen Nachfolger: „Erstellt einen Nachfolgeschlüssel, der die Bereiche und die Umgebung dieses Schlüssels übernimmt. Während des Übergangsfensters funktionieren beide Schlüssel, sodass Sie ohne Ausfall umstellen können.“ Legen Sie das Grace window (days) fest; 0 widerruft den alten Schlüssel sofort. Die Karte Rotation history verknüpft Vorgänger und Nachfolger.
- Rotieren Sie und kopieren Sie das neue Geheimnis („Schlüssel rotiert. Kopieren Sie das neue Geheimnis jetzt.“).
- Tragen Sie den neuen Schlüssel in die Integration ein.
- Prüfen Sie, ob sich Last used und Last used IP am alten Schlüssel nicht mehr ändern.
- Lassen Sie das Übergangsfenster enden oder widerrufen Sie den alten Schlüssel.
6. Im Zweifel sofort widerrufen
- Revoke Key: „Alle Integrationen, die diesen Schlüssel verwenden, werden sofort nicht mehr funktionieren. Diese Aktion kann nicht rückgängig gemacht werden.“
- Deactivate stoppt einen Schlüssel, den Sie eventuell zurückwollen; Activate startet ihn wieder.
- Bei einem Vorfall kann ein Owner mehrere oder alle Schlüssel gemeinsam widerrufen.
7. Die Schlüssel überwachen
| Signal | Wo |
|---|---|
| Last used, Last used IP, Total verifications | Die Seite des Schlüssels |
| Ein ruhender Schlüssel wird plötzlich von einer neuen Adresse benutzt | Ein Audit-Ereignis (api_key.anomaly.detected) |
| Fehlgeschlagene Verifizierungen | Audit-Ereignisse (api_key.verify.failed) |
| Erstellung, Rotation, Löschung, Berechtigungsänderungen | Das Audit-Log (api_key.created, api_key.rotated, api_key.deleted) |
| Missbrauch | Die AI-Firewall zeichnet Vorfälle zu Schlüsseln auf. Ihre Aktionen, einen Schlüssel zu drosseln oder abzuschalten, befinden sich In development. Siehe Die AI-Firewall. |
Die Schlüsselliste zeigt außerdem einen Hinweis für alte Schlüssel, die vor den Modulberechtigungen erstellt wurden: Öffnen Sie jeden davon und geben Sie ihm nur die Modulberechtigungen, die er braucht.
Schlüssel speichern
- Bewahren Sie Schlüssel im Geheimnisspeicher Ihrer Integration auf, niemals im Quellcode, in URLs oder in Tickets.
- Verwenden Sie
test-Schlüssel für Testsysteme, damit sie nicht mit Produktionsschlüsseln verwechselt werden können. - Wenn ein Schlüssel abgeflossen ist, widerrufen Sie ihn zuerst und finden Sie dann im Audit-Log heraus, von wo aus er benutzt wurde.