Vai al contenuto principale
Le chiavi API consentono agli script, agli strumenti senza codice e ai vostri servizi backend di chiamare l’API REST Flowella per conto della vostra organizzazione. Questa pagina spiega come gestire le chiavi dalla schermata Impostazioni → Chiavi API dell’app. Per conoscere le funzionalità dell’API, consultare la API reference.

​
Chi può gestire le chiavi API

Solo i ruoli proprietario o amministratore possono vedere Impostazioni → Chiavi API. I membri non hanno accesso a questa schermata e non possono chiamare gli endpoint API.

​
Creare una chiave API

1

Aprire Impostazioni → Chiavi API

Dalla navigazione a sinistra, andare su Impostazioni → Chiavi API.
2

Fare clic su Crea chiave

Assegnare alla chiave una etichetta che ne descriva lo scopo (ad esempio, n8n production, analytics export script). Le etichette sono visibili solo all’interno di Flowella e non vengono inviate nelle richieste API.
3

Scegliere un ambito (facoltativo)

Per impostazione predefinita, le chiavi ereditano l’intero set di endpoint API disponibili per il piano. È possibile limitare una chiave a un sottoinsieme di ambiti, ad esempio analisi di sola lettura o messaggi: solo invio.
4

Copiare immediatamente il segreto

Flowella mostra il token segreto esattamente una volta in una maschera di conferma. Copiatelo subito: non potrete visualizzarlo di nuovo. Se lo si perde, è necessario revocare la chiave e crearne una nuova.
Il segreto viene mostrato una sola volta. Flowella memorizza una copia con hash e non può recuperare il testo in chiaro. Trattate le chiavi come le password: non impegnatele mai nel controllo sorgente, non incollatele in chat o nei documenti condivisi.

​
Utilizzo di una chiave

Passare la chiave come token portatore a ogni richiesta: 
curl https://api.flowella.io/v1/messages \
  -H "Authorization: Bearer flwl_live_..." \
  -H "Content-Type: application/json"
Per i dettagli sugli endpoint, i limiti di velocità e i codici di errore, consultare la API reference.

​
Visualizzazione delle chiavi esistenti

L’elenco Impostazioni → Chiavi API mostra le chiavi esistenti:
  • Etichetta
  • Prefisso (i primi otto caratteri, come flwl_live_a1b2c3) - utile per la corrispondenza con i log.
  • Campo di applicazione
  • Creato in e creato da
  • Ultimo utilizzo - aggiornato a ogni richiesta andata a buon fine.
  • Status - attivo o revocato.
Il segreto in chiaro non viene mai visualizzato dopo la creazione.

​
Rotazione di una chiave

Non c’è una rotazione in loco: si crea una nuova chiave e si revoca la vecchia una volta che il servizio è passato all’altra.
1

Creare un sostituto

Seguite il flusso Create di cui sopra per creare una nuova chiave con lo stesso scopo.
2

Svelare il nuovo segreto

Aggiornare il servizio (o il flusso di lavoro n8n, l’ambiente Postman, ecc.) per utilizzare il nuovo token portatore.
3

Confermare che la nuova chiave è attiva

Osservate il campo Last used at della nuova chiave: si aggiorna entro un minuto dalla prima chiamata.
4

Revocare la vecchia chiave

Fare clic su Revoke sulla chiave precedente. Da quel momento qualsiasi richiesta che utilizzi il vecchio segreto restituisce 401 Unauthorized.

​
Revoca di una chiave

Fare clic su Revoke sulla riga, quindi confermare nella finestra di dialogo. La revoca è immediata: le richieste in corso che utilizzano quella chiave possono essere completate, ma la richiesta successiva restituisce 401. Una chiave revocata non può essere riattivata. La riga rimane visibile nell’elenco (in grigio, con il timestamp della revoca) in modo da avere una traccia di controllo.

​
Registro di controllo

Ogni evento di creazione, revoca e (se abilitato) di modifica dell’ambito viene scritto nel registro di audit dell’org con il proprio utente, IP e contesto di tracciamento. Se il vostro piano o contratto include la funzione di registro di audit, potete esaminare l’attività delle chiavi API.

​
Domande comuni

Non c’è un limite rigido per i piani hobby o a pagamento, ma un numero molto elevato di chiavi attive (oltre 50) rende difficile la rotazione e la revisione. Utilizzare una chiave per integrazione piuttosto che una per sviluppatore.
Le chiavi non scadono automaticamente. Si consiglia di ruotarle almeno ogni 12 mesi e di farlo immediatamente se una chiave potrebbe essere stata esposta.
Attualmente le chiavi sono assegnate all’organizzazione, non a un canale specifico. Lo scoping a livello di canale è in programma. Nel frattempo, scegliere il canale attivo tramite il payload della richiesta o il percorso.
Revocarlo immediatamente da questa pagina. Creare un sostituto con lo stesso scopo. Controllare il registro di audit per tutte le richieste che hanno utilizzato la chiave nel periodo in cui è stata esposta e ruotare tutti i segreti a valle che la chiave può aver creato (ad esempio, le chiavi di firma dei webhook).

​
Correlato

Introduzione all'API

Autorizzazione, errori, limiti di velocità e paginazione.

Ganci web

Spingete gli eventi ai vostri sistemi invece di eseguire il polling.

Team e ruoli

Solo i proprietari e gli amministratori possono gestire le chiavi API.

Sicurezza dei dati

Copertura del registro di audit per gli eventi di creazione/revoca delle chiavi.