Vai al contenuto principale

​
Panoramica

Le chiavi API forniscono accesso programmatico alla piattaforma itellicoAI, permettendoti di integrare gli agenti nelle tue applicazioni, automatizzare attività e creare flussi di lavoro personalizzati.

​
Cosa sono le Chiavi API?

Le chiavi API sono token sicuri che autenticano le tue richieste API senza richiedere credenziali di accesso utente. Caratteristiche principali:
  • Ambito account: Ogni chiave appartiene a un account specifico
  • Segrete: Tratta come una password - non condividere mai o committare nel controllo versione
  • Revocabili: Possono essere disabilitate o eliminate in qualsiasi momento
  • Tracciabili: Monitora il timestamp dell’ultimo utilizzo e l’attività

​
Creazione Chiavi API

​
Come Creare

1

Vai a Chiavi API

Vai a Impostazioni → Chiavi API nel tuo account
2

Clicca Crea Chiave API

Clicca sul pulsante Crea Chiave API
Finestra di dialogo Crea Chiave API con campi nome chiave e data di scadenza
Finestra di dialogo Crea Chiave API con campi nome chiave e data di scadenza
3

Inserisci un'Etichetta

Assegna alla tua chiave un nome descrittivo:
  • “Server di Produzione”
  • “Ambiente di Sviluppo”
  • “Pipeline CI/CD”
  • “App Mobile - iOS”
4

Imposta Scadenza (Opzionale)

Imposta opzionalmente una data di scadenza per la rotazione automatica della chiave
5

Copia la Chiave

⚠️ IMPORTANTE: La chiave completa viene mostrata solo una volta!Copiala immediatamente e conservala in modo sicuro.
6

Conserva in Modo Sicuro

Salva la chiave in:
  • Variabili d’ambiente
  • Gestore di segreti (AWS Secrets Manager, HashiCorp Vault, ecc.)
  • Gestore di password
Mai committare su git o condividere pubblicamente!
La chiave API completa viene visualizzata solo una volta alla creazione. Se la perdi, devi creare una nuova chiave.

​
Utilizzo Chiavi API

​
Header di Autenticazione

Includi la tua chiave API nell’header Authorization: 
curl https://api.itellico.ai/v1/agents \
  -H "Authorization: Bearer sk-a1b2c3d4.xyz789..." \
  -H "Content-Type: application/json"

​
Contesto Account

Le chiavi API sono associate al loro account. Quando crei una chiave in un account principale, può accedere sia all’account principale che a tutti i subaccount. Per accedere a un account specifico, includi l’ID account nel percorso URL: 
# Accedi all'account principale
curl https://api.itellico.ai/v1/accounts/me/agents \
  -H "Authorization: Bearer sk-a1b2c3d4.xyz789..." \
  -H "Content-Type: application/json"

# Accedi a un subaccount specifico
curl https://api.itellico.ai/v1/accounts/{account-id}/agents \
  -H "Authorization: Bearer sk-a1b2c3d4.xyz789..." \
  -H "Content-Type: application/json"

​
SDK

Utilizzando i nostri SDK ufficiali: 
from itellico import ItellicoAI

client = ItellicoAI(api_key="sk-a1b2c3d4.xyz789...")

# Elenca agenti
agents = client.agents.list()
Memorizza le chiavi API nelle variabili d’ambiente e non codificarle mai direttamente nel codice sorgente.

​
Gestione Chiavi API

​
Visualizzazione Chiavi

La pagina Chiavi API mostra:
  • Etichetta: Il tuo nome descrittivo
  • Chiave Parziale: Primi caratteri (es. sk-a1b2c3d4...)
  • Stato: Attiva, Revocata o Scaduta
  • Creata: Quando è stata creata la chiave
  • Ultimo Utilizzo: Quando è stata utilizzata l’ultima volta per una richiesta API
  • Scade: Data di scadenza (se impostata)
La chiave completa non viene mai mostrata dopo la creazione - solo i primi caratteri per l’identificazione.

​
Modifica Chiavi

Puoi aggiornare:
  • Etichetta: Modifica il nome descrittivo
  • Data di scadenza: Estendi o imposta la scadenza
Non puoi modificare:
  • La chiave stessa (crea una nuova invece)
  • L’account a cui appartiene

​
Revoca Chiavi

Per disabilitare temporaneamente una chiave senza eliminarla:
  1. Vai a Impostazioni → Chiavi API
  2. Trova la chiave nell’elenco
  3. Clicca Revoca
  4. La chiave viene disabilitata immediatamente
Perché revocare invece di eliminare?
  • Mantiene la chiave nei log per l’audit
  • Può essere riattivata se revocata per errore
  • Preserva la data di creazione e la cronologia

​
Riattivazione Chiavi

Per ripristinare una chiave revocata:
  1. Trova la chiave revocata nell’elenco
  2. Clicca Riattiva
  3. La chiave funziona immediatamente

​
Eliminazione Chiavi

Per rimuovere permanentemente una chiave:
  1. Vai a Impostazioni → Chiavi API
  2. Trova la chiave nell’elenco
  3. Clicca sul menu (⋯) → Elimina
  4. Conferma l’eliminazione
L’eliminazione è permanente e non può essere annullata. La chiave smetterà immediatamente di funzionare.

​
Stati delle Chiavi

StatoDescrizioneAccesso API
AttivaLa chiave funziona normalmente✅ Sì
RevocataDisabilitata manualmente❌ No
ScadutaOltre la data di scadenza❌ No

​
Migliori Pratiche

Crea chiavi separate per ogni ambiente:
  • Sviluppo: “Chiave Server Dev”
  • Staging: “Ambiente Staging”
  • Produzione: “Server di Produzione”
Vantaggi:
  • Revoca le chiavi dev senza influenzare la produzione
  • Traccia l’utilizzo per ambiente
  • Politiche di scadenza diverse per ambiente
Non codificare mai le chiavi API nel codice sorgente.Corretto:
import os
api_key = os.environ['ITELLICO_API_KEY']
Errato:
api_key = "sk-a1b2c3d4.xyz789..."  # NON FARLO!
File di ambiente (.env):
ITELLICO_API_KEY=sk-a1b2c3d4.xyz789...
Aggiungi a .gitignore:
.env
.env.local
*.key
Ruota le chiavi API periodicamente per sicurezza:Calendario raccomandato:
  • Produzione: Ogni 90 giorni
  • Staging: Ogni 180 giorni
  • Sviluppo: Annualmente o al cambio degli sviluppatori
Processo di rotazione:
  1. Crea nuova chiave con data di scadenza
  2. Aggiorna le applicazioni con la nuova chiave
  3. Testa accuratamente
  4. Revoca la vecchia chiave
  5. Elimina la vecchia chiave dopo 30 giorni
Usa le date di scadenza per:
  • Accesso temporaneo: Consulenti, demo, POC
  • Rotazione forzata: Chiavi di produzione impostate per scadere in 90 giorni
  • Funzionalità a tempo limitato: Test beta, prove
Esempio:
  • Crea chiave il 1° gennaio
  • Imposta scadenza al 1° aprile (90 giorni)
  • Ricevi notifica 7 giorni prima della scadenza
  • Ruota la chiave prima della scadenza
Controlla regolarmente i timestamp “Ultimo Utilizzo”:
  • Mai utilizzata: Elimina le chiavi inutilizzate
  • Timestamp vecchio: Potrebbe essere sicuro revocare
  • Attività recente: La chiave è attiva
Rivedi le tue chiavi API mensilmente per rimuovere quelle inattive.
Usa nomi chiave chiari e descrittivi:Etichette corrette:
  • “Server API Produzione - us-east-1”
  • “App Mobile - iOS - Produzione”
  • “CI/CD - GitHub Actions”
  • “Gestore Webhook - Staging”
Etichette errate:
  • “Chiave API 1”
  • “Test”
  • “La Mia Chiave”
  • “Nuova Chiave”
Usa un gestore di segreti in produzione:Opzioni:
  • AWS Secrets Manager
  • HashiCorp Vault
  • Azure Key Vault
  • Google Secret Manager
  • 1Password / LastPass (per team)
Vantaggi:
  • Archiviazione centralizzata dei segreti
  • Rotazione automatica
  • Log di audit
  • Controlli di accesso

​
Considerazioni sulla Sicurezza

Non committare mai le chiavi API nel controllo versione!Se committi accidentalmente una chiave:
  1. Revoca immediatamente la chiave
  2. Crea una nuova chiave
  3. Usa git filter-branch o BFG Repo-Cleaner per rimuoverla dalla cronologia
  4. Forza push al remoto
  5. Notifica i membri del team di scaricare l’ultima versione

​
Se una Chiave è Compromessa

1

Revoca Immediatamente

Vai a Impostazioni → Chiavi API e revoca la chiave compromessa
2

Crea Nuova Chiave

Genera una chiave sostitutiva con una nuova etichetta
3

Aggiorna le Applicazioni

Distribuisci la nuova chiave a tutte le applicazioni interessate
4

Esamina i Log

Controlla i log di utilizzo per attività sospette
5

Notifica il Team

Informa il tuo team sull’incidente
6

Indaga

Determina come la chiave è stata compromessa e previeni il ripetersi

​
Risoluzione Problemi

Cause:
  • Chiave API non valida
  • Chiave revocata o scaduta
  • Header Authorization mancante
  • Formato header errato
Soluzioni:
  • Verifica che la chiave sia attiva nelle Impostazioni
  • Controlla l’header: Authorization: Bearer sk-...
  • Assicurati che non ci siano spazi o caratteri extra
  • Crea una nuova chiave se persa
Cause:
  • La chiave non ha accesso all’account richiesto
  • Richiesta di un subaccount a cui la chiave non può accedere
  • L’account è inattivo
Soluzioni:
  • Verifica che la chiave sia stata creata nell’account principale o nel subaccount a cui stai accedendo
  • Controlla che l’ID account nell’URL sia corretto
  • Verifica che lo stato dell’account sia attivo
Cause:
  • Superati i limiti di frequenza
  • Troppe richieste simultanee
Soluzioni:
  • Implementa il backoff esponenziale
  • Memorizza in cache le risposte quando possibile
  • Passa a un piano di livello superiore
  • Distribuisci le richieste nel tempo
Possibili cause:
  • Uso della chiave errata (prefisso vs chiave completa)
  • Caratteri extra (nuove righe, spazi)
  • Revocata immediatamente dopo la creazione
Soluzioni:
  • Copia la chiave completa incluso il prefisso sk-
  • Rimuovi gli spazi dalla chiave memorizzata
  • Verifica che lo stato sia “Attiva”

​
FAQ

Nessun limite rigido, ma raccomandiamo:
  • Team piccoli: 3-5 chiavi
  • Team medi: 10-15 chiavi
  • Enterprise: Secondo necessità per ambiente
Le chiavi API create in un account principale possono accedere sia all’account principale che a tutti i suoi subaccount. Le chiavi create in un subaccount possono accedere solo a quel subaccount.
Le richieste API che usano quella chiave falliranno immediatamente con 401 Unauthorized. Aggiorna prima le tue applicazioni!
Sì. Il timestamp “Ultimo Utilizzo” mostra quando è stata utilizzata l’ultima volta. Per log dettagliati, contatta il supporto per i log di accesso API.
Solo se imposti una data di scadenza. Altrimenti, le chiavi rimangono attive fino alla revoca o eliminazione.
Sì! Ogni subaccount può creare chiavi API indipendenti associate al contesto di quel subaccount.

​
Prossimi Passi

Riferimento API

Esplora gli endpoint API disponibili

SDK

Usa i nostri SDK ufficiali Python e TypeScript

Gestione Team

Gestisci i membri del team