Archiviare una chiave API in modo sicuro: variabile d'ambiente, .gitignore, correzione delle fughe

Tieni la chiave in una variabile d'ambiente, non nel tuo codice, e tieni qualsiasi file .env fuori da git con una riga in .gitignore. Se una chiave è già finita da qualche parte pubblica, occupati prima della chiave e sistema il resto dopo: ripulire la cronologia di git mentre la chiave è ancora nel tuo codice e nei tuoi strumenti non risolve nulla.

Questo è il concetto. Questa guida è la versione pratica (le basi sono in What is an API key): tre comandi, una richiesta funzionante e un breve piano per il giorno storto.

Perché la chiave non appartiene al tuo codice#

Una chiave API è una password che spende i tuoi soldi. Chiunque la possieda può inviare richieste sul tuo saldo, e il servizio non può distinguerlo da te.

Il modo tipico in cui va storto è banale. Incolli la chiave in uno script per far funzionare la prima richiesta, lo script funziona, fai git push e il repository è pubblico. Oppure invii a un collega il tuo file di configurazione. Oppure fai uno screenshot di un errore con la chiave visibile nell'angolo. Ogni volta lo stesso risultato.

GitHub conosce bene questo schema. La sua scansione dei segreti (GitHub docs, consultato il 29 ottobre 2026) esamina l'intera cronologia Git su tutti i branch alla ricerca di credenziali hardcoded, e anche issue, pull request, discussioni, wiki e gist segreti, e genera un avviso quando ne trova una. Il che significa che eliminare la riga nel commit successivo non cambia nulla: il vecchio commit la contiene ancora.

Ecco lo stesso script prima e dopo.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key="<your-key>",  # pasted here: ends up in git
)

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

La seconda versione può andare su GitHub, in una chat o in una code review così com'è. La chiave vive sulla tua macchina, fuori dal file.

Passo 1: metti la chiave in una variabile d'ambiente#

Una variabile d'ambiente è un valore con un nome che il tuo terminale passa a ogni programma che avvia. Lo script chiede CHEAPTOKENS_API_KEY per nome e non vede mai da dove proviene.

Su macOS e Linux:

export CHEAPTOKENS_API_KEY="<your-key>"

Su Windows PowerShell:

setx CHEAPTOKENS_API_KEY "<your-key>"

Due dettagli ingannano le persone. export dura solo per quella finestra del terminale, quindi per mantenerla aggiungi la riga al tuo profilo della shell (~/.zshrc o ~/.bashrc). E setx non cambia la finestra in cui l'hai digitato: apri un nuovo terminale prima di testare.

Ora una richiesta completa. Usa l'endpoint compatibile con OpenAI, https://api.cheaptokens.dev/v1, e DeepSeek-V4-Flash con il suo id completo (deepseek-ai/DeepSeek-V4-Flash-0731; prendi gli id dalla CheapTokens docs, dato che i nomi differiscono tra i provider):

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

resp = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(resp.choices[0].message.content)
print(resp.usage)

Un breve saluto è una richiesta di circa 20 token in ingresso e 20 in uscita, che ai prezzi attuali è $0.0000023 (l'elenco completo è nella pricing page). Se non hai ancora inviato una prima richiesta, Your first API request with CheapTokens la illustra da zero.

La risposta del modello torna in choices[0].message.content, e usage mostra i token conteggiati. La chiave non appare mai nel file.

Passo 2: usa un file .env senza committarlo#

Digitare export in ogni nuova finestra diventa noioso. Un file .env tiene il valore in un unico posto, accanto al progetto:

CHEAPTOKENS_API_KEY=<your-key>

Python lo legge con python-dotenv (pip install python-dotenv):

from dotenv import load_dotenv
load_dotenv()  # fills os.environ from .env

Il file è sicuro solo se git non lo vede mai. Aggiungilo a .gitignore prima del primo commit:

echo ".env" >> .gitignore
git check-ignore -v .env

Se tutto è corretto, il secondo comando stampa qualcosa come .gitignore:1:.env .env: git ti dice quale regola sta ignorando il file. Se non stampa nulla, la regola non funziona. Su Windows, crea .gitignore in un editor con una riga .env, oppure usa Add-Content .gitignore .env: >> di PowerShell può scrivere in UTF-16, che git potrebbe ignorare.

Una trappola: .gitignore influisce solo sui file che git non sta ancora tracciando. Se .env è già stato committato una volta, esegui git rm --cached .env così git smette di tracciarlo, e considera la chiave al suo interno come esposta (ne parliamo più sotto). Un'abitudine ordinata è committare un .env.example con il nome della variabile e un segnaposto invece del valore, così un collega sa cosa impostare.

Se la chiave è trapelata: cosa fare, in ordine#

Magari la chiave è finita in un repo pubblico, magari era in uno screenshot, magari hai incollato l'intera configurazione in un thread di un forum. L'ordine conta più della velocità di ogni singolo passo.

La guida di GitHub stessa (stessa pagina, consultata il 29 ottobre 2026) è di ruotare immediatamente la credenziale; riscrivere la cronologia Git è opzionale e spesso non necessario una volta revocata la credenziale. Le persone tendono a fare il contrario: passano un'ora a ripulire la cronologia mentre la chiave funziona ancora. Non farlo.

Dopo la pulizia, invia una piccola richiesta di test, come nel Passo 1, e controlla il tuo saldo. Se risponde e saldo e richieste sembrano normali, la pulizia è finita; tieni d'occhio il saldo per i prossimi giorni. Una chiave che è stata pubblica va considerata esposta anche dopo averla rimossa dal codice, quindi monitora saldo e numero di richieste per qualcosa che non hai inviato, e non riutilizzare quella chiave in nuovi posti. Per i posti in cui una chiave tende a vivere, vedi Where to plug in your own API key.

Verifica da solo#