Genera e metti in sicurezza la tua chiave API
In questa pagina
Le credenziali che autenticano le tue richieste
La tua chiave API autentica ogni richiesta inviata ai modelli Mistral: senza di essa, nessuna chiamata viene accettata. Considerala come una password tecnica, con la differenza che viaggia attraverso codice, file di configurazione e pipeline di deployment, finendo quindi in molti più luoghi rispetto a una password standard. Chiunque ne entri in possesso può consumare la tua quota e generare costi sul tuo account.
Genera la tua prima chiave
Nella Console Mistral, apri il tuo spazio di lavoro e naviga nella sezione API Keys nella barra laterale. Clicca su Create new key e assegnale un nome descrittivo, come dev-chatbot-mars-2026. Questo nome non ha alcuna funzione tecnica, ma ti salverà la giornata quando sei chiavi coesisteranno nell’elenco e dovrai revocarne solo una: “chiave 3” non ti dice nulla, mentre dev-chatbot-mars-2026 ti dice tutto.
La chiave viene visualizzata una sola volta, al momento della creazione. Copiala immediatamente e conservala in un luogo sicuro. Se chiudi la finestra prima di averla copiata, non c’è modo di recuperarla: dovrai generarne una nuova. Una chiave Mistral è composta da un prefisso seguito da una lunga stringa alfanumerica. Non confonderla con il tuo ID spazio di lavoro o con un token JWT: a differenza di quest’ultimo, non scade automaticamente e rimane valida finché non la revochi.
Conservala senza mai inserirla direttamente nel codice
La regola d’oro è semplice: non inserire mai la tua chiave API direttamente nel codice sorgente. Il giorno in cui quel file finisce in un repository condiviso, la chiave finisce con esso. Usa sempre una variabile d’ambiente.
Su Linux e macOS, dichiarala nel terminale:
export MISTRAL_API_KEY="your-api-key-here"
Questa variabile scompare quando chiudi il terminale; per renderla persistente, aggiungi la riga al tuo file ~/.bashrc, ~/.zshrc o ~/.profile.
Su Windows, l’equivalente in PowerShell è il seguente:
$env:MISTRAL_API_KEY = "your-api-key-here"
E per sopravvivere a un riavvio della sessione:
[System.Environment]::SetEnvironmentVariable("MISTRAL_API_KEY", "your-api-key-here", "User")
In un progetto applicativo, la pratica più comune consiste nel creare un file .env alla radice:
MISTRAL_API_KEY=your-api-key-here
Aggiungi .env al tuo .gitignore immediatamente, prima del tuo primo commit, non dopo. In Python, la libreria python-dotenv legge questo file e inietta le variabili all’avvio, offrendoti la comodità di un file locale senza il rischio di versionare i segreti.
Ruota le tue chiavi
Sostituisci una chiave per tre motivi. Immediatamente, se è stata esposta in qualsiasi modo: un commit inviato a un repository Git pubblico, un messaggio Slack affrettato o tracce nei log del server. Regolarmente in produzione, con una cadenza ragionevole di ogni novanta giorni. E quando un collaboratore lascia l’azienda e aveva accesso, lo stesso giorno in cui restituisce il badge.
La procedura evita interruzioni del servizio se rispetti l’ordine:
- Genera una nuova chiave nella Console
- Aggiorna la variabile d’ambiente in tutti i tuoi deployment
- Verifica che tutto funzioni con la nuova chiave
- Revoca la vecchia chiave solo dopo questa verifica
Invertire i passaggi 3 e 4 è l’errore classico: revochi prima “per sicurezza”, solo per scoprire che un servizio dimenticato stava ancora usando la vecchia chiave. Questa rotazione a zero tempi di inattività garantisce che nessun componente fallisca durante la transizione.
Riduci la superficie di esposizione
Se più applicazioni chiamano l’API, crea una chiave per applicazione. Se una viene compromessa, devi solo revocare quella specifica chiave senza fermare le altre. Sulla stessa base, non riutilizzare mai una chiave di produzione in sviluppo: è proprio l’ambiente in cui i segreti circolano più liberamente.
Successivamente, monitora l’utilizzo dalla Console, che espone i log di utilizzo per ogni chiave. Un picco improvviso di token o chiamate da un indirizzo IP sconosciuto dovrebbe innescare una rotazione immediata, senza attendere la conferma dell’incidente.
Tre errori finali meritano una menzione perché li incontriamo ogni settimana. Una chiave pubblicata su un repository Git pubblico rimane leggibile nella cronologia anche dopo che il file è stato cancellato: l’unica risposta valida è la revoca. Una chiave inviata in chiaro via email o messaggistica istantanea viene archiviata per sempre su server che non controlli. E una chiave scaduta o revocata che persiste in un deployment produce errori 401 Unauthorized che spesso richiedono un’ora per essere diagnosticati, semplicemente perché nessuno ha pensato di controllare.
Punti chiave
- Genera le tue chiavi dalla sezione API Keys del tuo spazio di lavoro nella Console Mistral
- Conservale esclusivamente in variabili d’ambiente o in un gestore di segreti
- Esegui una rotazione regolare e una rotazione immediata in caso di esposizione
- Crea una chiave per applicazione per limitare l’impatto di una compromissione
- Aggiungi sempre
.enval tuo.gitignore