Chiavi API

Le chiavi API aprono l'accesso programmatico a dAio Business. Permettono alle tue applicazioni, script e sistemi di interrogare direttamente la piattaforma — dati meteo, qualità dell'aria, pollini, condizioni marine, intelligence settoriale — senza passare dall'interfaccia web. È il punto di ingresso per industrializzare le tue integrazioni: alimentare un ERP, attivare un processo di business, visualizzare previsioni nella tua dashboard.

Ogni chiave autentica le chiamate per conto della tua organizzazione e ne eredita i permessi. Combinata con i webhook, ti offre un canale completo: tu interroghi dAio su richiesta tramite l'API, e dAio ti notifica in tempo reale tramite i webhook.

Suggerimento: crea una chiave distinta per ogni utilizzo (un servizio, un ambiente, un partner). Potrai revocarne una senza interrompere le altre e tracciare con precisione quale integrazione consuma cosa.

A cosa serve una chiave API

Esigenza	La chiave API permette di…
Integrazione	Collegare dAio al tuo sistema informativo (ERP, CMMS, BI) senza intervento umano.
Automazione	Avviare elaborazioni pianificate (recupero giornaliero delle previsioni, scoring del rischio).
Diffusione	Visualizzare i dati dAio nelle tue applicazioni o nei tuoi portali.
Condivisione controllata	Dare a un partner un accesso limitato e revocabile, senza creare un account utente.

Nota: l'accesso API è riservato ai piani a pagamento. Un'organizzazione senza abbonamento attivo riceve una risposta 403 (« API access requires a paid plan ») a ogni chiamata.

Creare una chiave

La creazione di una chiave è riservata al proprietario (owner) e agli amministratori (admin) dell'organizzazione. Gli altri ruoli non possono né creare né revocare chiavi.

1. Accedi a Impostazioni > Chiavi API.
2. Clicca su Nuova chiave in alto a destra.
3. Inserisci un nome descrittivo che identifichi l'utilizzo della chiave (es. « Backend produzione », « Connettore Power BI », « Integrazione partner X »).
4. Clicca su Crea.
5. La chiave completa appare in un banner verde: copiala immediatamente con il pulsante di copia.

Attenzione: la chiave completa viene mostrata una sola volta, al momento della sua creazione. Non viene mai più visualizzata in seguito — la piattaforma ne conserva solo un'impronta cifrata. Se la perdi, dovrai generarne una nuova. Conservala senza indugio in un gestore di segreti (Vault, AWS Secrets Manager, variabili d'ambiente cifrate).

Una volta creata, la chiave appare nell'elenco con il suo nome, il suo prefisso (i primi caratteri, per identificarla senza rivelarla), un indicatore di stato (verde = attiva, rosso = revocata) e la sua data di ultimo utilizzo.

Utilizzare una chiave

Tutte le richieste all'API dAio devono includere la tua chiave nell'header HTTP X-API-Key. La base dell'API è https://api-dev.daio.app, e gli endpoint B2B sono prefissati con /api/v1/.

curl -H "X-API-Key: LA_TUA_CHIAVE_API" \
  "https://api-dev.daio.app/api/v1/weather/current?lat=48.8566&lon=2.3522"

Attenzione: l'header atteso è proprio X-API-Key, e non Authorization: Bearer. Una chiave non valida, revocata o trasmessa in un altro header restituisce una risposta 401 (« Invalid API key »).

Fai riferimento alla documentazione tecnica dell'API per l'elenco completo degli endpoint (meteo, previsioni orarie, qualità dell'aria, pollini, marina, elaborazione in batch) e il formato delle risposte.

Limiti di frequenza

Per garantire la stabilità del servizio, ogni chiave è soggetta a un limite di frequenza orario. Il contatore è proprio di ogni chiave e si reimposta ogni ora.

Piano	Richieste all'ora
Gratuito / senza abbonamento	Nessun accesso API
Solo · Team · Enterprise (dAio Business)	20.000

Quando il limite viene raggiunto, l'API restituisce una risposta 429 (« Rate limit exceeded ») accompagnata da un header Retry-After che indica il tempo di attesa prima di riprovare.

Nota: questo limite orario è distinto dalla quota mensile di richieste inclusa nella tua formula. Consulta il dettaglio delle quote per piano nella sezione Abbonamento.

Effettuare una rotazione di chiave

La rotazione rigenera una chiave conservandone il nome e la posizione nell'elenco. Usala per rinnovare periodicamente i tuoi segreti senza riconfigurare l'intera integrazione.

1. Nell'elenco, clicca sull'icona di rotazione (freccia circolare) accanto alla chiave.
2. Conferma l'operazione.
3. Il nuovo valore viene mostrato una sola volta — copialo immediatamente.
4. Aggiorna le tue applicazioni con questo nuovo valore.

Suggerimento: pianifica una rotazione ogni 90 giorni, e sistematicamente dopo l'uscita di un collaboratore che ha avuto accesso ai segreti o in caso di sospetta fuga.

Revocare una chiave

Per interrompere l'accesso di una chiave compromessa o inutilizzata:

1. Nell'elenco, clicca sull'icona di eliminazione (cestino) accanto alla chiave.
2. Conferma la revoca.

La revoca è immediata e irreversibile. Qualsiasi richiesta che utilizza la chiave revocata riceverà subito una risposta 401. La chiave resta visibile nell'elenco, contrassegnata come Revocata, a titolo di cronologia.

Sicurezza delle chiavi

Una chiave API equivale a una password: chiunque la possieda può interrogare l'API con i permessi della tua organizzazione.

Attenzione: non committare mai una chiave nel tuo codice sorgente o in un repository Git, nemmeno privato. Una chiave inviata per errore a un repository è considerata compromessa — revocala ed effettuane la rotazione senza attendere. Non trasmetterla mai in chiaro via e-mail, messaggistica o ticket di supporto.

• Conserva le chiavi in un gestore di segreti o in variabili d'ambiente, mai scritte direttamente nel codice.
• Non esporle lato client (applicazione web, mobile, JavaScript del browser): una chiamata API deve partire dal tuo server.
• Compartimenta: una chiave per ambiente (produzione, collaudo) e per utilizzo.
• Monitora la data di ultimo utilizzo: una chiave inattiva da molto tempo è una chiave da revocare.

Buone pratiche

• Nomina esplicitamente ogni chiave in base al suo utilizzo e al suo ambiente per individuare a colpo d'occhio cosa alimenta.
• Applica il privilegio minimo: crea chiavi dedicate e revocabili invece di un'unica chiave condivisa da tutte le tue integrazioni.
• Automatizza la rotazione ogni 90 giorni e integrala nelle tue procedure di uscita dei collaboratori.
• Gestisci i 429 lato client: rispetta l'header Retry-After e distribuisci le tue chiamate invece di concatenare le richieste.
• Revoca immediatamente qualsiasi chiave sospettata di essere compromessa — la revoca ha effetto senza indugio.
• Documenta internamente quale chiave serve a cosa e chi ne è responsabile, per audit di sicurezza sereni.

Suggerimento: associa le tue chiavi API ai webhook per un'integrazione completa — interroga dAio su richiesta e lascia che dAio ti notifichi gli eventi in tempo reale.