Como criar um token de API da Cloudflare para limpar a cache

Um token de API da Cloudflare capaz de limpar a cache precisa de exatamente duas permissões: Zone → Zone → Read, para listar as suas zonas, e Zone → Cache Purge → Purge, para as esvaziar. Cria-se em dash.cloudflare.com, em O meu perfil → Tokens de API → Criar token, com o modelo de token personalizado.

A Cloudflare permite autenticar-se na sua API de duas formas e só uma delas é boa ideia. Este guia trata da boa: um token com permissões restritas que sabe fazer duas coisas e mais nada.

As duas permissões necessárias

Limpar a cache através da API toca em dois endpoints, por isso o token precisa de duas permissões:

Permissão	Para que serve	Obrigatória?
`Zone → Zone → Read`	Listar as zonas da conta, com nomes e IDs	Sim
`Zone → Cache Purge → Purge`	Esvaziar o conteúdo em cache dessas zonas	Sim
`Account → Account Settings → Read`	Ler o nome das contas para agrupar as zonas por conta	Opcional

A lista acaba aqui. Um token de limpeza não tem nada que ver com os seus registos DNS, com as regras de firewall ou com a configuração SSL, e se um dia se perder, o pior que alguém consegue fazer com ele é esvaziar-lhe a cache.

Criar o token, passo a passo

Entre em dash.cloudflare.com.
Abra o menu de perfil no canto superior direito, vá a O meu perfil e depois ao separador Tokens de API. O link direto é dash.cloudflare.com/profile/api-tokens.
Carregue em Criar token, passe os modelos ao lado e escolha Criar token personalizado.
Dê-lhe um nome que reconheça daqui a seis meses. FlarePurge — iPhone é melhor do que token 3: com um token por dispositivo revoga só aquele que se perdeu.
Em Permissões, adicione Zone · Zone · Read e depois Zone · Cache Purge · Purge.
Em Recursos de zona, decida a que zonas o token chega. Todas as zonas é o cómodo, Zona específica é o prudente.
Deixe o filtro por endereço IP vazio a não ser que tenha IP fixo. Um telemóvel muda de rede a toda a hora e esse filtro acaba por o deixar de fora.
Defina um TTL se quiser que o token expire sozinho. Faz sentido para um colaborador externo, é escusado para o seu próprio dispositivo.
Carregue em Continuar para o resumo, confirme que aparecem exatamente as duas permissões acima e conclua com Criar token.

Porquê não a Global API Key

A Global API Key é o método antigo de autenticação: um endereço de email mais uma chave única que dá acesso administrativo completo a todas as zonas e a todas as definições da conta. Não se consegue restringir nem limitar a uma só operação.

Uma aplicação que lhe pede a Global API Key está a pedir as chaves do seu DNS, da sua firewall, da sua configuração SSL e da sua faturação, para carregar num botão que esvazia uma cache. O FlarePurge não a aceita, de propósito. Se uma ferramenta insiste em pedi-la, isso já lhe diz algo sobre a ferramenta.

Confirmar que o token funciona

Pode verificar um token a partir de qualquer terminal antes de o colar em lado nenhum. A Cloudflare tem um endpoint exatamente para isso:

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

Um token saudável responde com "status": "active". Se receber Invalid API Token, quase de certeza que foi copiado incompleto: o valor é longo e corta-se com facilidade.

Para confirmar que as permissões são as certas, e não apenas que o token é válido, liste as suas zonas:

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

Se aparecerem os seus domínios, Zone:Read está no sítio. Se receber uma lista vazia com success: true, o token é válido mas os seus recursos de zona não incluem nenhuma zona: volte atrás e alargue o âmbito.

Onde o token deve viver

Um token de limpeza é uma credencial e deve ser guardado como tal. O FlarePurge coloca-o no cofre seguro do sistema operativo: o porta-chaves nas plataformas Apple, o Keystore no Android, o gestor de credenciais no Windows. Nunca num ficheiro de texto nem num plist de preferências.

Um token por dispositivo. Se lhe roubarem o portátil revoga um, em vez de reemitir todos.
Revogue, não reaproveite. Apagar um token no painel é imediato e quem tiver uma cópia deixa de poder fazer o que quer que seja.
Não o cole num chat nem num ticket. Uma captura do painel também é uma fuga: no ecrã de criação o token está à vista.
Veja o registo de auditoria. A Cloudflare regista o uso dos tokens em Gerir conta → Registo de auditoria, por isso uma limpeza estranha nota-se.

E a seguir

Com o token criado, a decisão seguinte é que tipo de limpeza lançar. Limpar tudo é rápido e grosseiro, limpar URLs concretos é cirúrgico mas dá mais trabalho a preparar: a comparação está aqui. E se esbarrar em limites em limpezas grandes, veja os limites da API.