API-Referenz›Authentifizierung

Authentifizierung

DiffHook verwendet OAuth 2.0-Client-Anmeldeinformationen zur Authentifizierung von API-Anfragen. Sie tauschen einen API-Schlüssel gegen einen kurzlebigen Inhabertoken aus und senden diesen Token dann bei jeder Anfrage.

Schritt 1 – Holen Sie sich Ihren API-Schlüssel

Gehen Sie zu App → Einstellungen → API-Schlüssel und erstellen Sie einen Schlüssel. Sie erhalten zwei Werte:

  • Client-ID (client_id) – öffentliche Kennung. Es beginnt mit dh_live_ und wird mit einem zufälligen Suffix (URL-sichere Zeichen) fortgesetzt.
  • Client-Geheimnis (client_secret) – nur privates Geheimnis.

Schritt 2 – Fordern Sie ein Inhaber-Token an

Tauschen Sie Ihre Anmeldeinformationen gegen ein Token aus, indem Sie POST /api/oauth/token mit einem formcodierten Text aufrufen:

Token sind 24 Stunden gültig. Fordern Sie ein neues an, bevor das aktuelle abläuft.

Schritt 3 – Verwenden Sie den Inhabertoken

Übergeben Sie access_token im Authorization-Header bei jedem API-Aufruf:

curl https://www.diffhook.com/api/monitors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Fehlerantworten

Fehlender oder fehlerhafter Authorization-Header (401):

{ "error": "Authorization header missing or invalid" }

Abgelaufenes oder manipuliertes Token – erneut authentifizieren, um ein neues zu erhalten (401):

{ "error": "Invalid or expired token" }

Ungültige Anmeldeinformationen am Token-Endpunkt geben einen OAuth-Fehlertext (401) zurück:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Best Practices für die Sicherheit

  • Überweisen Sie niemals Ihr client_secret der Quellcodeverwaltung
  • Anmeldeinformationen in Umgebungsvariablen speichern (DIFFHOOK_CLIENT_ID, DIFFHOOK_CLIENT_SECRET)
  • Token verfallen nach 24 Stunden – integrieren Sie eine automatische Neuauthentifizierung in Ihre Integration
  • Rotieren Sie Schlüssel sofort, wenn einer verloren geht – widerrufen Sie den alten Schlüssel in den Einstellungen und generieren Sie einen neuen

Schlüsseldrehung

Um ohne Ausfallzeit zu rotieren:

  1. Generieren Sie einen neuen Schlüssel unter Einstellungen → API-Schlüssel
  2. Fordern Sie ein Token mit den neuen Anmeldeinformationen an und stellen Sie Ihre App damit bereit
  3. Entziehen Sie den alten Schlüssel, sobald der Verkehr vollständig verlagert ist