Le chiavi API permettono ai tuoi script e ai tuoi strumenti di leggere e modificare le zone DNS senza passare dall'interfaccia. Una chiave sostituisce il login: chi la possiede può fare, tramite l'API, esattamente ciò che le hai concesso.
Il caso d'uso più frequente è l'automazione dei record DNS: rinnovo automatico dei certificati, pubblicazione di un sito da una pipeline, aggiornamento massivo dei record da uno script.
Trovi la sezione in Sicurezza → Chiavi API. La pagina è disponibile solo al proprietario dell'account e agli amministratori: le chiavi valgono quanto un accesso, quindi non sono creabili dagli altri membri.
Clicca Crea chiave API e compila:
Alla conferma la chiave viene mostrata una sola volta. Copiala subito e conservala dove conservi le altre credenziali: alla chiusura della finestra non è più recuperabile, né da te né dal supporto. Se la perdi, revocala e creane una nuova.
La chiave va inviata come intestazione di autorizzazione a ogni chiamata:
Authorization: Bearer icbs_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
L'indirizzo di base delle chiamate è https://console.icbs.it/api/v1. Vedi Autenticazione per i dettagli.
Per verificare che tutto funzioni, usa Verificare la chiave: la risposta conferma quali permessi ha la chiave e su quali domini può agire. È il primo controllo da fare quando qualcosa non va.
curl -H "Authorization: Bearer $ICBS_API_KEY" \
https://console.icbs.it/api/v1/me
Dall'elenco, usa Revoca sulla riga della chiave. L'effetto è immediato: le integrazioni che la usano smettono di funzionare al primo tentativo successivo. La revoca non è annullabile.
Revoca una chiave quando: non ti serve più, il servizio che la usava è stato dismesso, oppure sospetti che sia finita dove non doveva (un repository pubblico, un log, una chat).
Per ogni chiave vedi il nome, il prefisso (la parte iniziale, l'unica visibile dopo la creazione), i permessi, i domini, l'ultimo utilizzo e lo stato.
L'ultimo utilizzo è il dato più utile per l'igiene periodica: una chiave che non viene usata da mesi è quasi sempre una chiave da revocare.
Una chiave può essere attiva, scaduta (ha superato la data di scadenza) o revocata. In entrambi gli ultimi due casi non funziona più.
L'elenco completo delle chiamate, con parametri, esempi e risposte, è nella sezione API, raggruppato per servizio: domini, DNS, hosting, email, FTP, database, backup, monitoraggio e gruppi.
Ogni chiave ha un tetto di richieste orarie, più alto in lettura che in scrittura. Superandolo le chiamate vengono rifiutate finché non riparte la finestra oraria: le intestazioni della risposta indicano quante richieste restano disponibili.
Se il tuo utente perde i permessi di modifica, le chiavi che hai creato passano automaticamente in sola lettura. Una chiave non può fare più di quanto puoi fare tu.