Gestione delle chiavi API
Una chiave API è una credenziale applicativa. Appartiene al tuo spazio di lavoro e un'applicazione che la possiede può chiamare Bird API entro gli ambiti assegnati. Puoi gestire le chiavi nella dashboard o tramite API. Per il contratto tecnico completo, consulta Autenticazione e chiavi API.
Dove si trovano le chiavi
Apri Chiavi API, in fondo alla barra laterale accanto a Webhooks e Logs. La pagina elenca nome, prefisso mascherato, ambiti, stato, scadenza e data di ultimo utilizzo di ogni chiave.
Per creare, modificare e revocare le chiavi serve il ruolo appropriato nello spazio di lavoro: Admin e Developer lo possiedono. Consulta Utenti, team e ruoli.
Creare una chiave
- Nella pagina delle chiavi API, scegli di creare una nuova chiave.
- Assegnale un nome basato sul suo scopo, ad esempio "Billing service production,", non sul nome di una persona.
- Scegli gli ambiti. Ogni ambito ha un livello read o write. Concedi solo gli ambiti e i livelli necessari all'applicazione.
- Crea la chiave e copia subito il segreto.
Il segreto viene mostrato una sola volta
La chiave completa appare una sola volta, al momento della creazione o della rotazione. Bird non può mostrare di nuovo il segreto. Copialo direttamente in un secret manager o nella configurazione di deploy. Se lo perdi, ruota o sostituisci la chiave.
Modifica gli ambiti di una chiave dalla sua riga nella pagina delle chiavi API. La modifica sostituisce l'insieme dei permessi e mantiene lo stesso segreto. Potrebbe essere necessario ruotare una chiave più vecchia per aggiungere un permesso. Consulta Autenticazione e chiavi API per le restrizioni sugli ambiti.
Revocare una chiave
Revoca una chiave quando non è più necessaria o sospetti che sia stata esposta. La revoca è permanente. La validazione delle chiavi usa una cache di breve durata, quindi una chiave revocata può continuare a funzionare fino a cinque secondi prima che le richieste falliscano l'autenticazione.
Se sospetti che una chiave sia stata esposta, revocala e distribuisci una sostituzione. Le richieste falliranno finché l'applicazione non utilizzerà una chiave attiva.
Per ruotare senza interruzioni, usa l'azione di rotazione e mantieni il periodo di grazia predefinito di 24 ore. Distribuisci la sostituzione prima che il periodo di grazia scada. Imposta un periodo di grazia più breve solo se puoi aggiornare i chiamanti prima.
Tutto viene registrato
Creazione delle chiavi, modifiche degli ambiti, rotazione e revoca compaiono nel log di audit della tua organizzazione. Una modifica degli ambiti registra gli ambiti aggiunti e rimossi. Includi le chiavi revocate nell'elenco delle chiavi per esaminarne i metadati.
Buone abitudini
- Usa una chiave per applicazione e ambiente. Separa le chiavi di staging da quelle di produzione, così puoi revocarne una senza influire sull'altra.
- Tieni d'occhio la colonna dell'ultimo utilizzo. Revoca le chiavi inattive che non servono più.
- Non inserire mai le chiavi nel codice lato client o nei repository pubblici. Le chiavi appartengono esclusivamente alla configurazione lato server e ai secret manager.
Prossimi passi
- Autenticazione e chiavi API: anatomia delle chiavi, dettagli sugli ambiti e contratto API
- Log di audit: esaminare gli eventi di creazione e revoca delle chiavi
- Utenti, team e ruoli: chi può gestire le chiavi
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.