La chiave: API Key
Chi bussa alla porta? La risposta più semplice è una chiave
- 15 minuti di lettura
Nel capitolo 1 hai visto le due domande: chi sei? e cosa puoi fare?. Qui ti serve la prima, nella forma più semplice che esista.
Il magazzino ricambi del deposito ha un'API. Ogni notte il programma di un fornitore, Valdora Ricambi, la interroga per leggere le scorte di guarnizioni, fusibili e fari. Nessuna persona è davanti a uno schermo: parla un programma con un altro programma. Come fa il magazzino a sapere che a bussare è proprio Valdora, e non un curioso qualunque?
Gli dà una chiave. Chi la porta, entra.
Il server non ricorda
Un controllore a un tornello di Porta Codice non ha memoria. Ti guarda, ti lascia passare, e un secondo dopo non sa più chi sei. Se torni indietro, sei di nuovo uno sconosciuto.
Un server fa lo stesso. Ogni richiesta arriva come se fosse la prima: il server non si ricorda di quella di un secondo fa. Si dice che HTTP è senza stato.
GET /magazzino ───────────▶ Server: «E tu chi sei?»
GET /magazzino ───────────▶ Server: «E tu chi sei?»
GET /magazzino ───────────▶ Server: «E tu chi sei?»Le tre richieste vengono dallo stesso programma, a un secondo di distanza, ma per il server sono tre sconosciuti. Ne segue una regola semplice: la prova di chi sei deve viaggiare dentro ogni richiesta, ogni volta, da capo.
Dove? Per capirlo, apri una richiesta.
La richiesta, a pezzi
Una richiesta ha tre parti, come una busta con una lettera:
POST /consegne HTTP/1.1 <- 1. la riga: il verbo e dove va
Host: 127.0.0.1:8000 <- 2. gli header: le scritte sulla busta,
Content-Type: application/json «nome: valore», uno per riga
X-API-Key: 9f2c4e7a1b6d0e83c5a2f4b7d9e1c3a5
{"ricambio": "guarnizione-P12", "pezzi": 50} <- 3. il corpo: la lettera dentro- La riga: il verbo (
GET,POST…) e il percorso. Anche la query (?ordine=nome) sta qui. - Gli header: informazioni sulla richiesta, una per riga, nella forma
nome: valore. Sono come le scritte sulla busta: il mittente, il tipo di lettera. - Il corpo: la lettera. Ce l'hanno solo
POSTePUT: unaGETha riga e header, e basta.
Gli header li hai già usati senza saperlo:
| Header | Valore | Chi lo mette | Quando |
|---|---|---|---|
Content-Type | application/json | Postman, o la libreria che usi | Ogni POST e PUT con un corpo JSON |
Authorization | Bearer eyJhbGciOi… | il client, con il biglietto | Dal capitolo 5 |
X-API-Key | 9f2c4e7a1b6d… | il client, con la chiave | In questo capitolo |
L'header è il posto giusto per la prova di chi sei perché c'è in ogni richiesta, anche in una GET senza corpo. E il server legge gli header prima del corpo: se la chiave non va, il corpo non lo apre nemmeno.
Il 401, in breve
Se la chiave manca o non va, il server risponde 401: non so chi sei. Il nome inganna («Unauthorized» sembra «non autorizzato»), ma vuol dire «non autenticato»: lo spiega il capitolo 1. Il 403 («so chi sei, ma qui no») qui non serve ancora: ne vedi un assaggio negli esercizi, e il capitolo sui permessiin arrivo lo spiega bene.
L'API Key
API Key vuol dire «chiave dell'API». Funziona in tre mosse:
- La dà il server, una volta sola, a mano. Si genera, si copia, si consegna a Valdora. Niente login, niente password.
- Viaggia in un header. A ogni richiesta, sempre la stessa:
X-API-Key:seguito dalla chiave. - Il server confronta. Ha la sua copia, nel file
.env. Uguale: entri. Diversa, o assente:401.
È una chiave per i programmi: si chiama server to server, da programma a programma. Il gestionale di un fornitore, l'app che chiama un servizio meteo. Nessuna persona fa il login. Le persone avranno una password e un biglietto: capitoli 4, 5 e 6.
I due lati della chiave
La chiave ha due lati, e a seconda del giorno li incontri tutti e due.
Sei tu il client. Chiami un'API di qualcun altro, e te la chiede. Ti registri sul sito del servizio, ti danno una chiave, e tu la metti nell'header di ogni richiesta. Il programma di Valdora fa questo:
import os
import httpx
from dotenv import load_dotenv
load_dotenv()
CHIAVE = os.environ["CHIAVE_MAGAZZINO"] # dal file .env
risposta = httpx.get("http://127.0.0.1:8000/magazzino", headers={"X-API-Key": CHIAVE})headers= è un dizionario: nome dell'header, valore. La chiave non è scritta nel codice: viene dall'ambiente, di cui parliamo tra poco.
Sei tu il server. La tua API apre solo a un programma. La chiave la generi tu, la dai al programma, e la controlli a ogni richiesta. È il magazzino di oggi, e il resto del capitolo racconta questo lato.
Fare la chiave
Una chiave deve essere lunga e a caso: 1234 si indovina in un attimo. La fa Python, con il modulo secrets, una volta sola, dalla cartella del progetto:
python3 -c "import secrets; print('CHIAVE_MAGAZZINO=' + secrets.token_hex(16))" > .env
cat .envCHIAVE_MAGAZZINO=6085ac6ded1fa2505cd0b84cdfac423aLa tua chiave sarà diversa, e non si copia da nessuna parte. Nemmeno quella che vedi qui: ormai la conosce chiunque legga la pagina.
Il comando, a pezzi:
| Pezzo | Cosa fa |
|---|---|
python3 -c "…" | esegue la riga di Python che c'è tra le virgolette |
secrets.token_hex(16) | tira fuori 16 byte a caso e li scrive in esadecimale: 32 caratteri, cifre e lettere da a a f |
'CHIAVE_MAGAZZINO=' + … | ci attacca davanti il nome e l'uguale: NOME=valore |
print(…) | stampa la riga |
> .env | invece di mostrarla, la scrive nel file .env |
Perché secrets e non random? random è fatto per i giochi: i suoi numeri sembrano a caso, ma seguono una regola che si può ricostruire. secrets è fatto per quello che deve restare segreto. Per una chiave, una password o un biglietto si usa sempre secrets.
Il file .env
Un file .env è un file di testo con una riga per voce, nella forma NOME=valore. Ci tieni quello che non si scrive nel codice: chiavi, password, indirizzi segreti. Comincia con un punto, quindi ls non lo mostra: con ls -a sì (nel Finder del Mac: Cmd+Shift+.).
La libreria python-dotenv (pip install python-dotenv) lo legge e mette le voci nell'ambiente, cioè in os.environ, un dizionario da cui Python le prende:
import os
from dotenv import load_dotenv
load_dotenv()
print(os.environ.get("CHIAVE_MAGAZZINO"))load_dotenv() cerca il .env partendo dalla cartella del file e salendo; se una voce c'è già nell'ambiente, non la cambia. Prima di chiamarla, os.environ.get("CHIAVE_MAGAZZINO") dà None; dopo, la chiave. Lo vedi con i tuoi occhi negli esercizi spiegati.
Due compagni del .env:
.gitignore: una riga.envdentro dice a Git di non caricarlo mai. Il.envvero non va mai su GitHub..env.example: il modello, con una chiave finta. Quello sì che si carica: dice a chi scarica il progetto quali voci servono, senza regalargli la tua chiave.
Il controllore, in italiano
Ora il lato server. A ogni richiesta, il magazzino deve decidere. Prima a parole:
Due 401 con due messaggi diversi: chi configura il programma capisce subito se la chiave non è arrivata o se è quella sbagliata. (Al login con la password sarà il contrario: lì un solo messaggio, per un buon motivo, che vedi nel capitolo 4.)
Il controllore, in Python
import os
from dotenv import load_dotenv
from fastapi import Depends, FastAPI, Header, HTTPException
load_dotenv()
CHIAVE_MAGAZZINO = os.environ.get("CHIAVE_MAGAZZINO")
if not CHIAVE_MAGAZZINO:
raise RuntimeError("Manca CHIAVE_MAGAZZINO: crea il file .env")
FORNITORE = "Valdora Ricambi"
SCORTE = {"guarnizione-P12": 140, "fusibile-F5": 62, "faro-led-M": 9}
app = FastAPI(title="Il magazzino ricambi")
def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
if chiave != CHIAVE_MAGAZZINO:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return FORNITOREIn cima, la chiave viene dall'ambiente, e se non c'è il programma si ferma subito con un messaggio chiaro: meglio che partire senza chiave e rompersi alla prima richiesta.
La riga nuova è quella del parametro. Leggila a pezzi:
chiave: str | None = Header(default=None, alias="X-API-Key")| Pezzo | Cosa vuol dire |
|---|---|
chiave | il nome in Python: lo scegli tu, è la variabile che userai nella funzione |
str | None | il tipo: una stringa, oppure None se l'header non c'è |
Header(…) | da dove: dagli header della richiesta, non dal percorso e non dal corpo |
default=None | cosa vale se l'header manca: None, e la funzione decide. Senza default=None, FastAPI risponde da solo 422 e il tuo messaggio non esce mai |
alias="X-API-Key" | il nome nella richiesta, trattino compreso. In Python un nome non può avere il trattino: l'alias fa da ponte |
Due cose da notare. La prima: controlla_chiave è una funzione senza @app. Non è una rotta: nessuno la chiama con un indirizzo. La chiama FastAPI, prima della rotta. La seconda: restituisce il nome del fornitore. Quel valore finirà alla rotta.
La rotta protetta
@app.get("/magazzino")
def leggi_magazzino(fornitore: str = Depends(controlla_chiave)) -> dict:
return {"fornitore": fornitore, "scorte": SCORTE}Il parametro fornitore: str = Depends(controlla_chiave) è l'unica riga che protegge la rotta. Il senso, quanto basta per ora: prima parte controlla_chiave. Se fa un raise, la risposta è quella (il 401) e la rotta non parte nemmeno. Se fa un return, il valore finisce nel parametro fornitore, e solo allora parte la rotta.
Lo conosci già da Depends(get_db) nel libro sul database. Come lavora davvero FastAPI, passo per passo, lo spiega da zero il prossimo capitolo.
Da dove arriva ogni dato
Il nome di un parametro lo scegli tu. Da dove arriva lo dice il tipo, oppure Header(…) e Depends(…). È la tabella del libro sul database, con una riga in più:
| Da dove | Nella richiesta | Nel def | Come lo riconosce FastAPI |
|---|---|---|---|
| Percorso | GET /treni/M12 | codice: str | c'è {codice} nel decoratore |
| Query | GET /treni?ordine=km | ordine: str = "id" | un tipo semplice, non nel percorso |
| Corpo | {"ricambio": "fusibile-F5", …} | dati: Consegna | il tipo è uno stampo (BaseModel) |
| Header | X-API-Key: 9f2c… | chiave: str | None = Header(…) | c'è Header(…) |
| Dipendenza | niente: la prepara FastAPI | fornitore: str = Depends(controlla_chiave) | c'è Depends(…) |
Provarla
Accendi il programma (con il .env nella stessa cartella): fastapi dev magazzino.py. Poi tre modi, tutti con le stesse tre richieste: senza chiave, con una chiave a caso, con la chiave giusta.
Con curl. L'opzione -H aggiunge un header:
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/magazzino
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/magazzino -H "X-API-Key: abc123"
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/magazzino -H "X-API-Key: 6085ac6ded1fa2505cd0b84cdfac423a"{"detail":"Manca la chiave"} → 401
{"detail":"Chiave sbagliata"} → 401
{"fornitore":"Valdora Ricambi","scorte":{"guarnizione-P12":140,"fusibile-F5":62,"faro-led-M":9}} → 200(-s toglie il resto del rumore, e -w aggiunge in fondo il codice della risposta.) Tre richieste, tre risposte, e il server non ricorda niente: confronta, ogni volta, da capo.
| La richiesta | Il controllore | La risposta |
|---|---|---|
GET /magazzino, nessun header | chiave è None | 401 Manca la chiave |
GET /magazzino, X-API-Key: abc123 | chiave != CHIAVE_MAGAZZINO | 401 Chiave sbagliata |
GET /magazzino, X-API-Key: 6085… | uguale: passa | 200, e fornitore vale "Valdora Ricambi" |
Da /docs. Apri http://127.0.0.1:8000/docs. Tra i parametri di GET /magazzino compare un campo X-API-Key, come se fosse un parametro della rotta: è il parametro del controllore, e FastAPI lo mostra. Try it out, scrivi la chiave nel campo, Execute. Lascialo vuoto e ottieni il primo 401.
Da Postman. Scheda Authorization → Auth Type: API Key. In Key scrivi X-API-Key, in Value la chiave, e in Add to scegli Header. Per non ricopiare la chiave a ogni richiesta, mettila in una variabile della collezione (come baseUrl, nel capitolo su Postman e curl) e scrivi {{chiave}} nel Value. Postman aggiunge da solo l'header X-API-Key: lo trovi, con tutti gli altri, nella scheda Headers.
Più chiavi: una per programma
Una chiave sola per tutti ha un guaio: se la perde un fornitore, la devi cambiare per tutti. Meglio una chiave per programma: un dizionario chiave → chi è.
CHIAVI = {
"chiave-lucente-3f9a": "Pulizie Lucente",
"chiave-rapida-b71c": "Nettezza Rapida",
"chiave-argento-52de": "Argento Servizi",
}
def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
impresa = CHIAVI.get(chiave)
if impresa is None:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return impresaIl get lo conosci dai dizionari: None se la chiave non c'è, senza errori. Il return ora dice chi è: ogni rotta sa quale programma sta chiamando. E se uno la perde, togli la sua riga dal dizionario e gli altri continuano a lavorare. (Chiavi scritte nel codice, qui, solo per imparare: sono finte. Quelle vere stanno nel .env o in un database.)
Le trappole
Quando la chiave non basta
La chiave è comoda per un programma, ma ha tre limiti:
- Non sa quale persona c'è dietro. Dice «è Valdora», non «è Rosa Bellini». Il controllore con più chiavi dice quale programma, non quale persona.
- Non scade. Una chiave rubata funziona finché qualcuno non se ne accorge.
- È sempre la stessa. Ogni richiesta porta la stessa prova: chi la intercetta una volta, la ha per sempre.
Per le persone serve il login: la password (capitolo 4), che si dà una volta sola, e il biglietto (capitolo 5), che scade ed è firmato. Il controllore del biglietto (capitolo 6) avrà la stessa forma di questo: cambia solo cosa legge e cosa restituisce.
Ricorda
- Il server non ricorda: la prova di chi sei viaggia dentro ogni richiesta.
- Una richiesta ha la riga, gli header (
nome: valore) e il corpo (soloPOSTePUT). La chiave sta in un header:X-API-Key. - L'API Key la dà il server a mano, è sempre la stessa, ed è per i programmi. Il server la confronta con la sua copia nel
.env. - La chiave si fa con
secrets.token_hex(16), mai conrandom, e si tiene nel.env: mai nel codice, mai su GitHub. - Il controllore: manca →
401«Manca la chiave»; è diversa →401«Chiave sbagliata»; è giusta → restituisce chi è. È una funzione senza@app. chiave: str | None = Header(default=None, alias="X-API-Key"): senzadefault=None,422.- La rotta si protegge con una riga:
fornitore: str = Depends(controlla_chiave). - Una chiave per programma: un dizionario
chiave → chi è. Chi perde la sua, la si toglie.