Creare un token API Cloudflare per svuotare la cache

Un token API Cloudflare in grado di svuotare la cache richiede esattamente due permessi: Zone → Zone → Read, per elencare le zone, e Zone → Cache Purge → Purge, per svuotarle. Si crea su dash.cloudflare.com, in Il mio profilo → Token API → Crea token, con il modello di token personalizzato.

Cloudflare permette di autenticarsi sulla sua API in due modi e solo uno è una buona idea. Questa guida parla di quello buono: un token con permessi ristretti che sa fare due cose e nient'altro.

I due permessi necessari

Svuotare la cache via API tocca due endpoint, quindi al token servono due permessi:

Permesso	A cosa serve	Obbligatorio?
`Zone → Zone → Read`	Elencare le zone dell'account, con nomi e ID	Sì
`Zone → Cache Purge → Purge`	Svuotare il contenuto in cache di quelle zone	Sì
`Account → Account Settings → Read`	Leggere il nome degli account per raggruppare le zone	Facoltativo

La lista finisce qui. Un token di purge non ha motivo di leggere i tuoi record DNS, toccare le regole del firewall o avvicinarsi alla configurazione SSL, e se dovesse trapelare, il peggio che può fare chi lo ha è svuotarti la cache.

Creare il token, passo per passo

Accedi su dash.cloudflare.com.
Apri il menu del profilo in alto a destra, vai su Il mio profilo e poi sulla scheda Token API. Il link diretto è dash.cloudflare.com/profile/api-tokens.
Premi Crea token, supera i modelli e scegli Crea token personalizzato.
Dagli un nome che riconoscerai fra sei mesi. FlarePurge — iPhone è meglio di token 3: con un token per dispositivo revochi solo quello che hai perso.
In Permessi aggiungi Zone · Zone · Read e poi Zone · Cache Purge · Purge.
In Risorse zona decidi a quali zone arriva il token. Tutte le zone è la scelta comoda, Zona specifica quella prudente.
Lascia vuoto il filtro per indirizzo IP a meno che tu non abbia un IP fisso. Un telefono cambia rete di continuo e quel filtro finirà per chiuderti fuori.
Imposta un TTL se vuoi che il token scada da solo. Utile per un collaboratore esterno, superfluo per il tuo dispositivo.
Premi Continua al riepilogo, controlla che riporti esattamente i due permessi qui sopra e conferma con Crea token.

Perché non la Global API Key

La Global API Key è il vecchio metodo di autenticazione: un indirizzo email più una chiave unica che concede accesso amministrativo completo a ogni zona e a ogni impostazione dell'account. Non si può restringere né limitare a una sola operazione.

Un'app che ti chiede la Global API Key ti sta chiedendo le chiavi del tuo DNS, del tuo firewall, della tua configurazione SSL e della tua fatturazione, per premere un pulsante che svuota una cache. FlarePurge non la accetta, di proposito. Se uno strumento insiste per averla, questo ti dice qualcosa sullo strumento.

Verificare che il token funzioni

Puoi verificare un token da qualsiasi terminale prima di incollarlo da qualche parte. Cloudflare ha un endpoint apposta:

curl -s https://api.cloudflare.com/client/v4/user/tokens/verify \
  -H "Authorization: Bearer IL_TUO_TOKEN" | jq

Un token sano risponde con "status": "active". Se ottieni Invalid API Token, quasi sempre è stato copiato incompleto: il valore è lungo e si tronca facilmente.

Per confermare che i permessi siano quelli giusti, e non solo che il token sia valido, elenca le tue zone:

curl -s "https://api.cloudflare.com/client/v4/zones?per_page=5" \
  -H "Authorization: Bearer IL_TUO_TOKEN" | jq '.result[].name'

Se compaiono i tuoi domini, Zone:Read è a posto. Se ottieni una lista vuota con success: true, il token è valido ma le sue risorse zona non includono nessuna zona: torna indietro e allarga l'ambito.

Dove deve stare il token

Un token di purge è una credenziale e va conservato come tale. FlarePurge lo mette nell'archivio sicuro del sistema operativo: il portachiavi sulle piattaforme Apple, il Keystore su Android, la gestione credenziali su Windows. Mai in un file di testo o in un plist di preferenze.

Un token per dispositivo. Se ti rubano il portatile ne revochi uno, invece di riemetterli tutti.
Revoca, non riciclare. Cancellare un token nel pannello ha effetto immediato e chi ne ha una copia non può farci più nulla.
Non incollarlo in una chat o in un ticket. Anche uno screenshot del pannello è una fuga: nella schermata di creazione il token è visibile.
Guarda il registro di audit. Cloudflare annota l'uso dei token in Gestisci account → Registro di audit, quindi un purge inatteso si vede.

E adesso

Creato il token, la decisione successiva è che tipo di purge lanciare. Svuotare tutto è rapido e grossolano, svuotare URL precise è chirurgico ma più lungo da preparare: qui il confronto. E se sbatti contro i limiti su purge grandi, guarda i limiti dell'API.