Chiavi Virtuali (Virtual Key) nell’AI Gateway
La chiave virtuale (Virtual Key) è una credenziale emessa dall’AI Gateway per l’accesso agli endpoint proxy del gateway. Invece di fornire la chiave API reale del fornitore, consegni una chiave virtuale alle tue applicazioni e ai tool AI; la chiave reale rimane salvata solo lato gateway. Questo evita che le chiavi vere si diffondano, consentendo però di configurare restrizioni, limiti di utilizzo, rotazione e revoca in modo indipendente per ogni chiave virtuale. Questa guida copre la gestione completa del ciclo di vita delle chiavi virtuali.
Perché utilizzare una chiave virtuale
- Protegge le chiavi reali — Applicazioni e tool interagiscono solo con la chiave virtuale; la vera API Key del fornitore non viene mai esposta.
- Permessi granulari per ogni uso — Puoi creare chiavi virtuali differenti per ogni progetto o strumento, assegnando permessi su modelli e canali e imponendo limiti dedicati.
- Revoca immediata — Se una chiave viene compromessa o non serve più, puoi subito revocarla o ruotarla senza impattare le altre chiavi.
Prerequisiti
- Accesso effettuato con un account ServBay.
- Almeno un canale disponibile aggiunto nella pagina Canali.
Creazione di una chiave virtuale
Accedi a AI Gateway → Chiavi (Keys) e clicca su Crea (Create):
- Nome — Identifica la chiave e il suo utilizzo (es.
claude-code,my-app-dev). - Descrizione (opzionale) — Ulteriore annotazione.
- Data di scadenza — Può non scadere mai oppure puoi impostare una data.
- Canali autorizzati (opzionale) — Seleziona tramite tag i canali su cui la chiave può operare; lascia vuoto per non limitare.
- Modelli autorizzati (opzionale) — Indica se la chiave può richiamare solo alcuni modelli; lascia vuoto per nessuna restrizione.
- Rate limit (opzionale):
- RPM / TPM — Numero massimo di richieste o token al minuto.
- RPD / TPD — Numero massimo di richieste o token al giorno.
Il testo della chiave viene mostrato una sola volta
Dopo la creazione, la chiave viene mostrata in chiaro solo una volta (es. servbay-sk-xxxxxxxx...): copiala e salvala subito! Una volta chiusa la finestra vedrai solo il prefisso (per riconoscimento) e non potrai più recuperare il valore completo. Se la perdi, sarà necessario crearne una nuova tramite “Rotazione”.
Lista delle chiavi
La lista delle chiavi mostra per ciascuna chiave virtuale:
- Prefisso — Es.
servbay-sk-abcd..., utile per riconoscere la chiave. - Stato — Attiva (active), revocata (revoked), scaduta (expired).
- Data creazione / ultimo utilizzo.
- Tag relativi ai permessi — Modelli e canali consentiti, eventuali limiti di utilizzo.
Gestione delle chiavi
Dalla lista, puoi eseguire queste operazioni su ogni chiave:
| Operazione | Descrizione | Effetto |
|---|---|---|
| Modifica (Edit) | Cambia nome, descrizione, permessi su modelli/canali o rate limit | Immediato, la chiave rimane la stessa |
| Rotazione (Renew) | Genera un nuovo valore in chiaro, il vecchio smette subito di valere | Aggiorna tutte le app/tool che usano la chiave |
| Revoca (Revoke) | Disabilita subito la chiave, conservando i log di audit | Irreversibile; le richieste saranno rifiutate |
| Elimina (Delete) | Cancella del tutto la chiave | Irreversibile |
Rotazione vs Revoca
- Rotazione (Renew): La chiave rimane, cambia solo il valore; ideale quando sospetti una fuga di dati, ma vuoi continuare a usare la stessa configurazione per app e strumenti. Ricorda di aggiornarli!
- Revoca (Revoke): Rende la chiave inutile in modo permanente, mantenendo però il record per audit. Indicata quando la chiave non serve più.
Entrambe le azioni richiedono una doppia conferma.
Relazione con la modalità “One-Click Takeover”
Utilizzando la funzione One-Click Takeover per collegare uno strumento AI al gateway, viene creata automaticamente una chiave virtuale esclusiva per quell’app e impostata sulla sua configurazione. Puoi comunque gestire queste chiavi anche manualmente nella pagina “Chiavi”.
FAQ (Domande Frequenti)
- D: Cosa faccio se non copio la chiave in chiaro appena creata?
- R: Non è possibile recuperarla: esegui una “Rotazione” e usa il nuovo valore generato aggiornando la configurazione dell’applicazione.
- D: Differenza tra revoca ed eliminazione della chiave?
- R: La revoca mantiene il record (per eventuali audit) ma la chiave diventa inattiva; l’eliminazione cancella ogni traccia. In entrambi i casi la chiave non sarà più valida.
- D: Se limito i “modelli autorizzati”, che succede se l’app prova un altro modello?
- R: Il gateway rifiuterà qualsiasi richiesta per modelli non autorizzati. Assicurati che quelli usati siano inclusi oppure togli il vincolo.
- D: Cosa succede se raggiungo i limiti di rate (“rate limit”)?
- R: Tutte le richieste oltre i limiti RPM/TPM/RPD/TPD verranno bloccate dal gateway. Puoi verificare l’uso effettivo in Statistiche e regolare i limiti secondo necessità.
Conclusione
Le chiavi virtuali ti consentono di fornire capacità AI ad app e strumenti in modo sicuro, limitato e sempre revocabile. Grazie ai permessi su modelli/canali e al rate limiting, puoi creare credenziali su misura per ogni scenario e ruotare o revocare l’accesso in qualsiasi momento, senza mai esporre le vere API Key dei fornitori.
