Ogni chiamata all'API deve portare una chiave valida. Le chiavi si creano da Sicurezza → Chiavi API: vedi Chiavi API.
La chiave va nell'intestazione Authorization, con schema Bearer:
Authorization: Bearer icbs_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Non inserire mai la chiave nell'indirizzo della richiesta: gli URL finiscono nei log dei proxy e nella cronologia del browser, le intestazioni no.
Negli esempi di questa documentazione la chiave è letta da una variabile d'ambiente, come dovresti fare anche nei tuoi script:
export ICBS_API_KEY="icbs_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
curl -H "Authorization: Bearer $ICBS_API_KEY" \
https://console.icbs.it/api/v1/me
Alla creazione della chiave scegli cosa può fare. Ogni chiamata di questa documentazione indica il permesso richiesto: se manca, la risposta è 403 e l'operazione non viene eseguita.
I permessi sono divisi per servizio — domini, DNS, hosting, email, FTP, database, backup, monitoraggio, gruppi — e separano sempre la lettura dalla scrittura. Li vedi tutti al momento di creare la chiave, con la descrizione di cosa consentono.
Una chiave può essere legata a domini specifici. In quel caso le chiamate sugli altri domini rispondono 404, esattamente come se il dominio non esistesse: la chiave non rivela l'esistenza di ciò a cui non ha accesso.
Tutte le risposte sono in JSON.
In caso di errore il corpo ha sempre questa forma:
{
"error": {
"message": "Invalid or missing API key",
"status": 401
}
}
| Codice | Significato |
|---|---|
200 | Operazione riuscita. |
400 | Dati inviati non validi — per esempio un tipo di record inesistente o un campo obbligatorio vuoto. |
401 | Chiave assente, non valida, scaduta o revocata. |
403 | Chiave valida ma senza il permesso necessario, oppure dominio fuori da quelli assegnati. |
404 | Dominio o record inesistente, oppure non accessibile a questa chiave. |
429 | Superato il limite di richieste. |
500 | Errore imprevisto sul nostro lato. |
La risposta 401 è identica in tutti i casi che la generano: che la chiave sia inesistente, revocata, scaduta o semplicemente sbagliata, il messaggio non cambia. È voluto — distinguerli aiuterebbe solo chi sta provando a indovinare una chiave. Se ricevi un 401 che non ti aspetti, usa Verificare la chiave per capire in che stato si trova.
Ogni chiave ha un tetto di richieste orarie, più alto in lettura che in scrittura. Superandolo le chiamate rispondono 429 finché non riparte la finestra oraria.
Ogni risposta riuscita include due intestazioni per regolare la frequenza delle chiamate senza andare a tentativi:
| Intestazione | Contenuto |
|---|---|
X-RateLimit-Limit | Richieste consentite nella finestra oraria. |
X-RateLimit-Remaining | Richieste ancora disponibili nella finestra corrente. |
Se stai facendo molte chiamate consecutive, leggi X-RateLimit-Remaining e rallenta prima di arrivare a zero.