API-Schlüssel

API-Schlüssel authentifizieren Ihre Anfragen an die DiffHook-API und identifizieren die Ressourcen des Teams, auf die Sie zugreifen.

Einen Schlüssel erstellen

1. Gehen Sie zu App → Einstellungen → API-Schlüssel
2. Klicken Sie auf Neuer API-Schlüssel
3. Geben Sie ihm eine beschreibende Bezeichnung (z. B. production-server, ci-pipeline).
4. Client-ID und Client-Geheimnis sofort kopieren – sie werden nur einmal angezeigt

Die Client-ID ist Ihre öffentliche Kennung: Sie beginnt mit dh_live_. Nach der Erstellung wird in den Einstellungen jeder Schlüssel nach Bezeichnung und vollständiger Client-ID aufgelistet, sodass Sie die ID jederzeit kopieren können. Das Geheimnis wird nie wieder enthüllt.

Wenn Sie vergessen haben, das Geheimnis zu kopieren, löschen Sie den Schlüssel und erstellen Sie einen neuen.

Schlüsselberechtigungen

Alle Schlüssel haben derzeit vollen Zugriff auf die Ressourcen Ihres Teams (Monitore, Protokolle, Einstellungen). Schlüssel pro Bereich (schreibgeschützt, protokolliert usw.) stehen auf der Roadmap.

Wenn Sie heute den Zugriff einschränken müssen, erstellen Sie ein separates Team für schreibgeschützte Integrationen und laden Sie dort eine begrenzte Anzahl von Mitgliedern ein.

Signaturgeheimnisse

Ihr Signaturgeheimnis ist von Ihrem API-Schlüssel getrennt. Es wird ausschließlich zum Signieren ausgehender Webhook-Nutzlasten verwendet, damit Ihr Server überprüfen kann, ob sie von DiffHook stammen.

Finden Sie es unter App → Einstellungen → API-Schlüssel → Signaturgeheimnis.

Weitere Informationen finden Sie unter Signaturen verifizieren.

Einen Schlüssel rotieren

1. Erstellen Sie einen neuen Schlüssel und aktualisieren Sie Ihre Anwendungen, um ihn zu verwenden
2. Stellen Sie sicher, dass der neue Schlüssel in der Produktion funktioniert
3. Löschen Sie den alten Schlüssel aus App → Einstellungen → API-Schlüssel

Es gibt keinen automatischen Weg zur Schlüsselrotation, der einen vorhandenen Schlüssel direkt ersetzt. Befolgen Sie immer den Ablauf „Erstellen → Migrieren → Löschen”, um Ausfallzeiten zu vermeiden.

Signaturgeheimnis rotieren

Gehen Sie zu App → Einstellungen → API-Schlüssel → Signaturgeheimnis rotieren.

Nach der Rotation:

• Alle zukünftigen Webhooks werden sofort mit dem neuen Geheimnis signiert
• Laufende Webhook-Zustellungen können noch die alte Signatur tragen
• Aktualisieren Sie das Geheimnis Ihres Servers, bevor Sie das alte widerrufen

Einen Schlüssel widerrufen

Löschen Sie den Schlüssel aus App → Einstellungen → API-Schlüssel. Der Widerruf erfolgt sofort – der Schlüssel kann nicht mehr zum Anfordern neuer Token verwendet werden.

Allerdings bleiben Inhabertoken, die bereits mit diesem Schlüssel ausgegeben wurden, bis zu ihrem natürlichen Ablauf gültig (bis zu 24 Stunden nach ihrer Generierung).

Wichtige Best Practices für die Sicherheit

• Übergeben Sie niemals Schlüssel an die Quellcodeverwaltung. Verwenden Sie Umgebungsvariablen oder einen Secrets-Manager (z. B. AWS Secrets Manager, Doppler, Vault).
• Verwenden Sie einen Schlüssel pro Umgebung. Behalten Sie separate Schlüssel für Entwicklung, Staging und Produktion, damit Sie einen Schlüssel widerrufen können, ohne dass sich dies auf andere auswirkt.
• Schlüssel regelmäßig rotieren. Behandeln Sie jeden Schlüssel, der älter als 90 Tage ist, als Kandidaten für die Rotation.
• Überwachen Sie auf Lecks. Wenn ein Schlüssel in einem öffentlichen Repository oder Protokoll erscheint, widerrufen Sie ihn sofort und erstellen Sie einen neuen.

Fehlerbehebung bei Authentifizierungsfehlern

401 Unauthorized

• Anmeldeinformationen fehlen, sind fehlerhaft oder der Schlüssel wurde widerrufen
• Für API-Schlüssel: Verwenden Sie ein JWT von POST /api/oauth/token

403 Forbidden

• Der Schlüssel ist gültig, hat aber keinen Zugriff auf die angeforderte Ressource (z. B. einen Monitor, der zu einem anderen Team gehört).