Chiavi API

Genera e gestisci chiavi API per l'accesso programmatico.

Le chiavi API abilitano l'accesso programmatico ai tuoi agenti. Usale per integrare Agentkit nelle tue applicazioni o collegare servizi di terze parti.

La creazione di chiavi e l’uso dell’API richiedono un piano Hobby o superiore con fatturazione attiva. I membri del workspace possono continuare a visualizzare e revocare le chiavi esistenti dopo aver perso tale diritto di accesso. Passa a un piano superiore →

Creare una chiave API

Vai al tuo workspace
Fai clic su Chiavi API nella barra laterale
Fai clic su Crea chiave API
Conferma nella finestra di dialogo

La nuova chiave appare nell'elenco e può essere rivelata o copiata in qualsiasi momento.

Visualizzare e copiare le chiavi

Ogni chiave nell'elenco è mascherata per impostazione predefinita. Usa l'icona a forma di occhio per rivelare una chiave e l'icona di copia per copiarla negli appunti.

Usare le chiavi API

Includi la chiave nelle richieste API:

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"chatbotId": "uuid", "messages": [{"role": "user", "content": "Hello"}]}'

Documentazione API completa →

Gestire le chiavi

Visualizzare tutte le chiavi

Tutte le chiavi del workspace sono elencate nella pagina Chiavi API.

Eliminare una chiave

Trova la chiave nell'elenco
Fai clic sull'icona del cestino
Conferma l'eliminazione

Le chiavi eliminate smettono di funzionare immediatamente.

Revocare le chiavi dopo la scadenza dell’accesso

Se il tuo workspace perde l’accesso all’API, accedi ed elimina le chiavi non più necessarie dalla pagina Chiavi API. Non devi rinnovare la fatturazione per revocarle. Devi comunque essere membro del workspace. Se hai attivato MFA, completa la verifica MFA prima di gestire le chiavi. Fino ad allora, il database nasconde le chiavi del workspace e ne rifiuta l’eliminazione. Questo non ripristina l’uso dell’API né il permesso di creare chiavi.

In precedenza Agentkit verificava il diritto di accesso a pagamento all’API prima di eliminare una chiave. Anche le policy del database richiedevano tale diritto per leggere o eliminare chiavi. La perdita dell’accesso poteva quindi bloccare la rimozione di una credenziale esistente.

La correzione separa la creazione dalla rimozione. L’appartenenza al workspace regola la lettura e l’eliminazione delle chiavi esistenti, mentre una policy separata del database applica MFA. Creare e aggiornare chiavi richiede ancora il diritto di accesso all’API. L’azione di eliminazione verifica sia l’ID della chiave sia quello del workspace e segnala il successo solo quando il database restituisce una riga eliminata.

Questo esempio semplificato descrive la modifica del controllo:

Before
  Require API entitlement before deleting an existing key.

After
  Delete only a key belonging to the requested workspace.
  Require a returned deleted row before reporting success.
  Keep membership checks and enforce MFA in the database.

I test dell’applicazione simulano il client del database. Verificano i filtri e la gestione dei risultati, non le policy del database. I test SQL usano account sintetici e annullano le modifiche. I risultati attesi comprendono:

Controllo	Livello del test	Risultato atteso
Un membro autorizzato revoca senza diritto di accesso all’API	Simulazione dell’applicazione	Nessuna query sul diritto di accesso; filtri per chiave e workspace; il successo richiede una riga restituita
Un membro autorizzato revoca senza diritto di accesso all’API	SQL	Una chiave del proprio workspace eliminata
Un membro crea una chiave senza diritto di accesso	Simulazione dell’applicazione e SQL	Rifiutato
Un membro tenta di eliminare una chiave di un altro workspace	SQL	Nessuna riga eliminata
Il requisito MFA non è soddisfatto	SQL	Nessuna riga eliminata
La chiave richiesta non esiste o non è visibile al chiamante	Simulazione dell’applicazione	L’azione segnala un errore

Queste sono aspettative di regressione, non risultati di una prova in produzione. Applica lo stesso schema di test alle credenziali temporanee nei flussi degli agenti. Modifica l’accesso prima della pulizia, poi verifica sia la riuscita della pulizia autorizzata sia il rifiuto di quella non autorizzata.

Best practice di sicurezza

Non esporre mai le chiavi

Non fare commit delle chiavi nei repository git
Non includere le chiavi nel codice lato client
Usa variabili d'ambiente

Ruota le chiavi periodicamente

Crea nuove chiavi periodicamente
Aggiorna le tue applicazioni
Elimina le chiavi vecchie

Usa chiavi separate

Crea chiavi diverse per:

Produzione e sviluppo
Applicazioni diverse
Membri del team o servizi diversi

Ambito delle chiavi

Le chiavi API sono limitate al workspace in cui vengono create e hanno accesso a:

Tutti gli agenti del workspace
Endpoint dell'API di chat
Gestione dei webhook

Le chiavi non possono:

Gestire i membri del team
Accedere alla fatturazione
Creare altre chiavi API

Connessione con Zapier

Quando ti connetti a Zapier:

Crea una chiave API dedicata per Zapier
Usa questa chiave nella connessione con Zapier
Tieni questa chiave separata da altri usi

Configura Zapier →

Risoluzione dei problemi

Errore "Invalid API key"

Verifica che la chiave sia stata copiata correttamente
Controlla che non ci siano spazi iniziali o finali
Verifica che la chiave non sia stata eliminata

Errore "Key not authorized"

Assicurati che l'agente appartenga al tuo workspace
Verifica che il workspace della chiave corrisponda
Per le richieste API, verifica che il tuo workspace sia su un piano Hobby o superiore con fatturazione attiva

La chiave non funziona dopo la creazione

Prova ad aggiornare la pagina
Attendi 30 secondi per la propagazione
Crea una nuova chiave se il problema persiste