Chiavi API

Le chiavi API autenticano le tue richieste all'API DiffHook e identificano le risorse del team a cui stai accedendo.

Creazione di una chiave

1. Vai su App → Impostazioni → Chiavi API
2. Fai clic su Nuova chiave API
3. Assegnagli un'etichetta descrittiva (ad esempio production-server, ci-pipeline)
4. Copia immediatamente l'ID cliente e il Segreto cliente: verranno visualizzati solo una volta

L'ID cliente è il tuo identificatore pubblico: inizia con dh_live_. Dopo la creazione, Impostazioni elenca ciascuna chiave per etichetta e ID client completo in modo da poter copiare l'ID in qualsiasi momento; il segreto non viene mai più mostrato.

Se dimentichi di copiare il segreto, elimina la chiave e creane una nuova.

Autorizzazioni chiave

Tutte le chiavi attualmente hanno pieno accesso alle risorse del tuo team (monitor, registri, impostazioni). Le chiavi per ambito (sola lettura, solo log e così via) sono sulla roadmap.

Se hai bisogno di limitare l'accesso oggi, crea un team separato per le integrazioni di sola lettura e invita lì membri limitati.

Segreti di firma

Il tuo segreto di firma è separato dalla chiave API. Viene utilizzato esclusivamente per firmare i payload webhook in uscita in modo che il tuo server possa verificare che provengano da DiffHook.

Puoi trovarlo in App → Impostazioni → Chiavi API → Firma segreta.

Vedi Verifica le firme per come usarlo.

Rotazione di una chiave

1. Crea una nuova chiave e aggiorna le tue applicazioni per usarla
2. Verificare che la nuova chiave funzioni in produzione
3. Elimina la vecchia chiave da App → Impostazioni → Chiavi API

Non esiste una scorciatoia per la rotazione della chiave che sostituisca automaticamente una chiave sul posto: segui sempre il flusso crea → migra → elimina per evitare tempi di inattività.

Rotazione del segreto della firma

Vai a App → Impostazioni → Chiavi API → Ruota segreto di firma.

Dopo la rotazione:

• Tutti i futuri webhook verranno firmati immediatamente con il nuovo segreto
• Le consegne a bordo potrebbero ancora riportare la vecchia firma
• Aggiorna il segreto del tuo server prima di revocare quello vecchio

Revoca di una chiave

Elimina la chiave da App → Impostazioni → Chiavi API. La revoca è immediata: la chiave non può più essere utilizzata per richiedere nuovi token.

Tuttavia, i token al portatore già emessi con quella chiave rimangono validi fino alla loro scadenza naturale (fino a 24 ore dopo la loro generazione).

Principali pratiche migliori per la sicurezza

• Non impegnare mai le chiavi nel controllo del codice sorgente. Utilizza variabili di ambiente o un gestore di segreti (ad esempio AWS Secrets Manager, Doppler, Vault).
• Utilizza una chiave per ambiente. Mantieni chiavi separate per sviluppo, gestione temporanea e produzione in modo da poterne revocare una senza influire sugli altri.
• Ruota le chiavi periodicamente. Considera qualsiasi chiave più vecchia di 90 giorni come candidata alla rotazione.
• Monitora eventuali fughe di dati. Se una chiave appare in un archivio pubblico o in un registro, revocala immediatamente e creane una nuova.

Risoluzione dei problemi relativi agli errori di autenticazione

401 Unauthorized

• Le credenziali sono mancanti, non sono corrette o la chiave è stata revocata
• Per le chiavi API: utilizzare un JWT da POST /api/oauth/token

403 Forbidden

• La chiave è valida ma non ha accesso alla risorsa richiesta (ad esempio un monitor appartenente a un team diverso)