Autenticazione e chiavi
Ogni chiamata all’API si autentica con una chiave, passata nell’header
Authorization. Non ci sono altri metodi: niente cookie di sessione, niente
OAuth, niente parametri nell’URL.
Le chiavi iniziano sempre con ub_. Vanno usate solo da un server: una chiamata
che arriva da un browser viene rifiutata con 403 prima ancora di controllare la
chiave.
Chiave personale o chiave dell’area di lavoro
Esistono due tipi di chiave, e la differenza sta in chi paga e in chi la controlla.
Usa una chiave personale quando sviluppi o provi qualcosa per conto tuo. Usa una chiave dell’area di lavoro per un’integrazione dell’azienda che deve continuare a funzionare anche quando chi l’ha scritta cambia ruolo. Le chiavi dell’area di lavoro sono spiegate in Chiavi API dell’area di lavoro.
La pagina Sviluppatore
La voce Sviluppatore compare a chi è nell’elenco di Accesso delle Chiavi API, deciso dagli amministratori. Di partenza l’accesso è aperto a tutta l’area di lavoro; se non vedi la voce, l’hanno spenta o riservata ad altri. Vale anche per gli Admin: configurano la funzionalità, ma la voce la vedono solo se sono nell’elenco.
La pagina si apre dalla voce Sviluppatore e ha il titolo Chiavi API, con Crea chiave API in alto a destra.
Le schede sono tre:
Un Membro vede la pagina ma non può creare chiavi, nemmeno se il permesso è acceso per il suo ruolo. Un Editor può crearle solo se un amministratore gli ha dato il permesso in Ruoli: di partenza ce l’hanno solo gli Admin.
Creare una chiave personale
Apri Sviluppatore e premi Crea chiave API
Se il pulsante non c’è, il tuo ruolo non ha il permesso di creare chiavi: chiedilo a chi amministra l’area di lavoro.
Dai un nome che dica dove viene usata
Backend produzione, Job notturno fatture, Staging: serve a capire cosa stai spegnendo il giorno che la revochi. Una chiave personale può chiamare sia i completamenti sia gli embedding, quindi non ci sono permessi da scegliere.
Dopo la creazione, nell’elenco resta una versione mascherata del tipo
ub_5f3a91…840a, con le colonne Permessi, IP, Creata e Ultimo
uso. Userbot conserva solo l’impronta crittografica della chiave: nessuno,
supporto compreso, può rileggerla o rimandartela.
Gli amministratori ricevono una notifica per ogni chiave creata, e la creazione finisce nel Registro di audit. Se arriva una notifica per una chiave che nessuno aveva previsto, va revocata.
Quando una chiave smette di funzionare
Una chiave è legata alla persona che la possiede (per quelle personali) o all’Admin che l’ha creata (per quelle dell’area di lavoro). Smette di funzionare in questi casi:
- è stata revocata, a mano o perché quella persona è stata rimossa dall’area di lavoro: la rimozione revoca tutte le sue chiavi, comprese quelle dell’area di lavoro che aveva creato;
- è scaduta. La durata la decide l’amministratore in Impostazioni › Sicurezza e controllo › Sicurezza e accesso, voce Scadenza predefinita chiavi API: Nessuna scadenza oppure 1, 3, 6, 12 o 24 mesi, con 12 mesi di partenza. Vale per le chiavi create da quel momento;
- la persona non è più nell’elenco di Accesso delle Chiavi API, o la funzionalità è stata spenta. In questo caso la chiave non è revocata: torna a funzionare se la persona rientra nell’elenco.
Per i sistemi che devono restare accesi, quindi, una chiave personale è una scelta fragile: basta un cambio di gruppo per spegnerla. → Sicurezza dell’area di lavoro
Revocare una chiave
Nell’elenco, apri il menu ⋯ sulla riga della chiave e scegli Revoca, poi conferma. Nello stesso menu, Intervalli IP cambia la whitelist senza rigenerare la chiave.
La revoca ha effetto immediato e non si annulla. Ogni sistema che stava usando
quella chiave riceve 401 alla chiamata successiva, senza periodo di
tolleranza. Prepara la chiave nuova prima di revocare la vecchia.
Gli errori di autenticazione
Il corpo dell’errore contiene un campo code che distingue i casi.
Nessuno di questi errori si risolve riprovando: va sistemata la chiave o la configurazione.
Buone pratiche
Una chiave per ambiente e per servizio. Produzione, staging e il portatile di chi sviluppa non condividono la stessa chiave. Così, quando una va sostituita, spegni una cosa sola e sai quale.
Mai nel codice sorgente. La chiave sta in una variabile d’ambiente o in un gestore di segreti. Una chiave finita in un repository va considerata compromessa anche se il repository è privato: la cronologia di git la conserva.
Mai lato client. Una chiave dentro un’applicazione web, mobile o desktop è leggibile da chiunque abbia l’applicazione. Le chiamate partono dal tuo server.
Ruotale prima che scadano. La rotazione senza interruzioni ha un ordine preciso.
Se una chiave è esposta
Revocala subito, poi crea la sostituta: in questo ordine, non nell’altro. Una chiave lasciata attiva “finché non sistemiamo” continua a spendere. Controlla poi in Costi, budget e analytics cosa è stato consumato mentre era in circolazione.