Come ruoto una chiave API?

Ruotare regolarmente le chiavi API è una pratica di sicurezza importante. Ecco come ruotare le chiavi in modo sicuro senza interrompere il servizio.

Perché ruotare le chiavi API?

• Best practice di sicurezza: Riduce l’esposizione se una chiave viene mai compromessa

• Cambiamenti nel team: Quando gli sviluppatori lasciano l’azienda o cambiano ruolo

• Possibile compromissione: Se ritieni che una chiave possa essere stata esposta

• Conformità: Alcune policy di sicurezza richiedono la rotazione periodica delle chiavi

• Cambiamenti dell’ambiente: Quando migri l’infrastruttura o fai refactoring

Processo di rotazione standard (zero downtime)

Passo 1: Crea una nuova chiave

1. Accedi a Impostazioni → API

2. Clicca "Crea nuova chiave API"

3. Assegnale un nome descrittivo (es., "Produzione Web v2")

4. Copia subito la nuova chiave: viene mostrata solo una volta

5. Conservala in modo sicuro

Passo 2: Aggiorna la tua applicazione

• Distribuisci la nuova chiave alla tua applicazione (variabili d’ambiente, secret manager, ecc.)

• Riavvia l’applicazione per caricare la nuova chiave

• Verifica che la nuova chiave funzioni correttamente

• Monitora eventuali errori

Passo 3: Monitora la transizione

• Mantieni entrambe le chiavi attive temporaneamente

• Controlla Impostazioni → API per vedere le date di "Ultimo utilizzo"

• Attendi finché la vecchia chiave non mostra più attività recente

• Assicurati che tutte le istanze/servizi siano passati alla nuova chiave

Passo 4: Elimina la vecchia chiave

• Dopo aver confermato che la vecchia chiave non è più in uso

• Elimina o disattiva la vecchia chiave in Impostazioni → API

• Documenta la rotazione per i tuoi archivi

Processo di rotazione rapido (se compromessa)

Se una chiave è sicuramente compromessa e devi agire immediatamente:

1. Elimina prima la chiave compromessa in Impostazioni → API

2. Crea una nuova chiave di sostituzione

3. Distribuisci rapidamente la nuova chiave a tutte le applicazioni

4. Accetta un breve downtime per prevenire accessi non autorizzati

5. Monitora i log di utilizzo per individuare eventuali attività sospette

6. Contatta l’assistenza se necessario

Strategia di rotazione multi-ambiente

Per i sistemi di produzione, usa un approccio a fasi:

Settimana 1: Sviluppo

• Crea e distribuisci la nuova chiave all’ambiente di sviluppo

• Testa accuratamente

Settimana 2: Collaudo

• Distribuisci la nuova chiave all’ambiente di staging

• Esegui test di integrazione

• Monitora eventuali problemi

Settimana 3: Produzione

• Distribuisci la nuova chiave in produzione durante un periodo a basso traffico

• Monitora attentamente

• Mantieni la vecchia chiave attiva per 24-48 ore come fallback

Settimana 4: Pulizia

• Verifica che la vecchia chiave non mostri attività

• Elimina la vecchia chiave

• Aggiorna la documentazione

Esempio di automazione

Script per aiutare a verificare che la rotazione della chiave sia completa:

#!/bin/bash
# check-api-key.sh
OLD_KEY="sk_live_OLD123..."
NEW_KEY="sk_live_NEW789..."
echo "Testing old key..."
OLD_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \
  -H "x-api-key: $OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}')
echo "Testing new key..."
NEW_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \
  -H "x-api-key: $NEW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}')
echo "Old key status: ${OLD_RESPONSE: -3}"
echo "New key status: ${NEW_RESPONSE: -3}"
if [ "${NEW_RESPONSE: -3}" == "200" ]; then
  echo "✅ New key is working!"
else
  echo "❌ New key failed!"
fi

Best practice

• Ruota regolarmente: Ogni 90 giorni per le chiavi di produzione

• Documenta le rotazioni: Mantieni un registro di quando le chiavi sono state ruotate e del perché

• Testa prima di eliminare: Verifica sempre che la nuova chiave funzioni prima di rimuovere la vecchia

• Usa più chiavi: Separare le chiavi per ambiente rende la rotazione più semplice

• Automatizza quando possibile: Usa strumenti di gestione dei segreti che supportano la rotazione automatica

Checklist dopo la rotazione

Conferma questi punti dopo la rotazione:

• ✅ Tutte le istanze di produzione che usano la nuova chiave

• ✅ Tutti gli ambienti staging/dev aggiornati (se usi la stessa chiave)

• ✅ Variabili d’ambiente aggiornate

• ✅ Secret CI/CD aggiornati

• ✅ Documentazione aggiornata

• ✅ Notifica ai membri del team

• ✅ Vecchia chiave eliminata

• ✅ Rotazione registrata per scopi di audit