Chiavi virtuali del Gateway AI (Virtual Key)
Una chiave virtuale (Virtual Key) è una credenziale emessa dal Gateway AI per accedere agli endpoint proxy del gateway. Tu distribuisci le chiavi virtuali alle applicazioni e agli strumenti AI, mentre le vere API Key dei provider restano custodite solo lato gateway. In questo modo eviti che le chiavi reali si disperdano in giro e, allo stesso tempo, puoi applicare a ciascuna chiave virtuale permessi, limiti di velocità, rotazioni e revoche in modo indipendente. Questo articolo descrive la gestione completa del ciclo di vita delle chiavi virtuali.
Perché usare le chiavi virtuali
- Proteggere le chiavi reali — Applicazioni e strumenti entrano in contatto solo con le chiavi virtuali, mentre le chiavi reali dei provider non vengono mai esposte.
- Permessi granulari per utilizzo — Puoi creare chiavi virtuali diverse per progetti/strumenti diversi, limitando per ciascuna i modelli disponibili, i canali utilizzabili e la velocità.
- Revocabili in qualsiasi momento — Se una chiave viene compromessa o non serve più, puoi revocarla o ruotarla direttamente, senza impatto sulle altre chiavi.
Prerequisiti
- Aver effettuato l'accesso con un account ServBay.
- Aver aggiunto almeno un canale disponibile nella pagina Canali.
Creare una chiave virtuale
Accedi alla pagina Gateway AI → Chiavi (Keys) e fai clic su Crea (Create):
- Nome — Serve a identificare lo scopo della chiave (ad es.
claude-code,my-app-dev). - Descrizione (opzionale) — Note aggiuntive.
- Data di scadenza — Può essere impostata come "mai" oppure con una data specifica.
- Canali consentiti (opzionale) — Tramite selezione multipla basata su tag, limita la chiave affinché possa essere instradata solo verso i canali specificati; se lasciato vuoto, non ci sono restrizioni.
- Modelli consentiti (opzionale) — Limita la chiave affinché possa chiamare solo i modelli specificati; se lasciato vuoto, non ci sono restrizioni.
- Limiti di velocità (opzionale):
- RPM / TPM — Numero massimo di richieste / Token al minuto.
- RPD / TPD — Numero massimo di richieste / Token al giorno.
Il testo in chiaro è sempre recuperabile
Una volta creata con successo, il gateway mostra la chiave in chiaro (nel formato servbay-sk-xxxxxxxx...). Il gateway conserva il testo in chiaro localmente, quindi potrai recuperarlo in seguito dai dettagli della chiave; solo le chiavi storiche create in passato tramite hash non hanno un testo in chiaro recuperabile (la richiesta di recupero restituisce 409). Se sospetti che la chiave sia stata compromessa, esegui direttamente la "Rotazione".
Elenco delle chiavi
L'elenco delle chiavi mostra per ogni chiave virtuale:
- Prefisso — Ad es.
servbay-sk-abcd..., utile per il riconoscimento. - Stato — Attiva (active), revocata (revoked), scaduta (expired).
- Data di creazione / Data dell'ultimo utilizzo.
- Etichette dei permessi — Modelli/canali consentiti, limiti di velocità.
Gestire le chiavi
Nell'elenco delle chiavi, per ciascuna chiave puoi eseguire le seguenti operazioni:
| Operazione | Descrizione | Effetto |
|---|---|---|
| Modifica (Edit) | Modifica nome, descrizione, modelli/canali consentiti, limiti di velocità | Ha effetto immediato, la chiave in sé non cambia |
| Rinnova (Renew) | Rigenera il testo in chiaro, il vecchio testo in chiaro diventa immediatamente invalido, mentre il nuovo è recuperabile in qualsiasi momento | È necessario aggiornare tutte le applicazioni e gli strumenti che utilizzano questa chiave |
| Revoca (Revoke) | Disattiva immediatamente la chiave, ma conserva i registri di audit | Irreversibile; le richieste con questa chiave verranno rifiutate |
| Elimina (Delete) | Elimina definitivamente la chiave | Irreversibile |
Rinnovo vs Revoca
- Rinnovo (Renew): la chiave rimane la stessa, cambia solo il nuovo testo in chiaro — adatto a scenari in cui sospetti una compromissione ma vuoi continuare a usare la stessa configurazione di chiave; ricorda di aggiornare tempestivamente chi la utilizza.
- Revoca (Revoke): rende la chiave definitivamente invalida ma conserva il record, utile per l'audit — adatto a scenari in cui hai confermato che una chiave non è più necessaria. Sia il rinnovo che la revoca richiedono una doppia conferma.
Rapporto con l'acquisizione con un clic
Quando utilizzi l'acquisizione con un clic per indirizzare uno strumento AI al gateway, il gateway crea automaticamente una chiave virtuale dedicata per quello strumento e la scrive nella configurazione dello strumento. Puoi anche gestire manualmente queste chiavi create automaticamente nella pagina delle chiavi.
Domande frequenti (FAQ)
- D: Ho dimenticato di copiare la chiave in chiaro, cosa faccio?
- R: Puoi recuperare il testo in chiaro dai dettagli della chiave; solo le chiavi storiche create in passato tramite hash non sono recuperabili, in tal caso esegui la "Rotazione".
- D: Qual è la differenza tra revoca ed eliminazione?
- R: La revoca conserva il record della chiave (utile per l'audit), mentre l'eliminazione lo cancella completamente. Entrambe rendono la chiave immediatamente invalida.
- D: Dopo aver limitato i "modelli consentiti", cosa succede se l'applicazione richiede altri modelli?
- R: Il gateway rifiuterà le richieste per modelli non inclusi nei permessi della chiave. Assicurati che i modelli usati dall'applicazione siano nella lista consentita, oppure rimuovi la restrizione.
- D: Cosa succede quando viene attivato un limite di velocità?
- R: Le richieste che superano RPM/TPM/RPD/TPD verranno limitate dal gateway. Puoi monitorare l'utilizzo effettivo nella pagina Statistiche e poi regolare i limiti massimi.
Conclusione
Le chiavi virtuali ti permettono di distribuire le capacità AI ad applicazioni e strumenti con il minimo privilegio e in modo revocabile. Grazie ai limiti su modelli/canali consentiti e ai limiti di velocità, puoi creare credenziali su misura per ogni scenario d'uso e ruotarle o revocarle in qualsiasi momento, senza mai dover toccare le vere API Key dei provider.
