Autenticazione

DiffHook utilizza le credenziali client OAuth 2.0 per autenticare le richieste API. Scambia una chiave API con un token al portatore di breve durata, quindi invia quel token a ogni richiesta.

Passaggio 1: ottieni la chiave API

Vai su App → Impostazioni → Chiavi API e crea una chiave. Riceverai due valori:

• ID cliente (client_id): identificatore pubblico. inizia con dh_live_ e continua con un suffisso casuale (caratteri sicuri per l'URL).
• Segreto cliente (client_secret): solo segreto privato.

Passaggio 2: richiedi un token al portatore

Scambia le tue credenziali con un token chiamando POST /api/oauth/token con un corpo codificato nel modulo:

I token sono validi per 24 ore. Richiedine uno nuovo prima che quello attuale scada.

Passaggio 3: utilizzare il token al portatore

Passa access_token nell'intestazione Authorization su ogni chiamata API:

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

Risposte agli errori

Intestazione Authorization mancante o non corretta (401):

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

Token scaduto o manomesso: autenticarsi nuovamente per ottenerne uno nuovo (401):

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

Le credenziali errate sull'endpoint del token restituiscono il corpo dell'errore OAuth (401):

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

Migliori pratiche di sicurezza

• Non affidare mai il tuo client_secret al controllo del codice sorgente
• Memorizza le credenziali in variabili di ambiente (DIFFHOOK_CLIENT_ID, DIFFHOOK_CLIENT_SECRET)
• I token scadono dopo 24 ore: crea una riautenticazione automatica nella tua integrazione
• Ruota le chiavi immediatamente se ne perde una: revoca la vecchia chiave in Impostazioni, generane una nuova

Rotazione della chiave

Per ruotare senza tempi di inattività:

1. Genera una nuova chiave in Impostazioni → Chiavi API
2. Richiedi un token con le nuove credenziali e distribuisci la tua app con esso
3. Revocare la vecchia chiave una volta che il traffico è stato completamente spostato