Resposta rápida
Para criar um Cloudflare API token com segurança, abra My Profile > API Tokens, escolha um modelo ou um token personalizado, conceda apenas a permissão necessária e limite os recursos à conta, zona ou serviço usado. Quando possível, defina uma data de expiração e restrinja os endereços IP autorizados antes de revisar e gerar o segredo.
Use token de usuário para tarefas pontuais que devem agir em nome de uma pessoa. Para CI/CD e integrações duráveis, prefira um Account API token quando o endpoint necessário for compatível, porque ele não depende da permanência de um funcionário. Nunca use a Global API Key se uma permissão menor resolver o trabalho.
O que mudou no painel em 6 de novembro
A Cloudflare reformulou a criação de User API tokens para aproximar a experiência da usada nos tokens de conta. O novo fluxo organiza melhor a edição de políticas e permite adicionar, alterar ou remover blocos antes da criação.
Expiração e filtragem por endereço IP agora aparecem de forma mais clara durante a configuração. A mudança é de interface e revisão: o token continua pertencendo ao usuário que o criou e continua limitado pelas permissões desse usuário. Não trate a aparência semelhante como se o token tivesse se transformado em uma credencial independente da pessoa.
Token de usuário ou token da conta
Um User API token age em nome do usuário e só pode receber um subconjunto das permissões que essa pessoa já possui. Ele funciona bem em scripts temporários, operações administrativas supervisionadas e ferramentas pessoais. Se a função da pessoa mudar ou sua associação for removida, a integração pode deixar de ter o acesso esperado.
Um Account API token funciona como principal de serviço e é mais adequado para automações que precisam sobreviver à troca de funcionários. A criação exige capacidade de provisionamento de tokens ou função de Super Administrator, e nem todos os produtos aceitam esse formato. Consulte a matriz de compatibilidade antes de migrar uma integração existente.
Como criar o token com escopo mínimo
No painel da Cloudflare, escolha uma finalidade clara e dê ao token um nome que identifique sistema e ambiente, como deploy-worker-producao. Um modelo pode acelerar a configuração, mas ainda precisa ser revisado. Em um token personalizado, selecione primeiro a categoria da permissão, depois Read ou Edit e por fim os recursos alcançados.
Read permite leitura e listagem quando aplicável. Edit inclui criar, ler, atualizar, excluir e listar. Se a automação só consulta dados, não conceda Edit. Em permissões de zona, selecione a zona específica em vez de todas as zonas. Em permissões de conta, escolha apenas a conta usada pelo processo.
- Abra My Profile > API Tokens para token de usuário ou Manage Account > API Tokens para token da conta.
- Escolha um modelo ou Create Custom Token e defina um nome ligado ao sistema e ao ambiente.
- Adicione somente as permissões Read ou Edit necessárias para o endpoint usado.
- Restrinja os recursos à conta, zona ou serviço que a integração realmente precisa.
- Defina validade e origem de rede antes de abrir o resumo final.
- Revise cada bloco e só então gere e armazene o segredo em um cofre.
Como usar expiração e restrição por IP
Sem TTL, o token é duradouro e não expira automaticamente. O painel permite definir quando ele começa a valer e quando deixa de ser aceito. As datas escolhidas na interface representam 00:00 UTC; use a API quando precisar de horário mais preciso. Planeje a rotação antes do vencimento para não transformar uma proteção em interrupção inesperada.
A filtragem por IP aceita faixas em CIDR. Depois de adicionar uma regra Is in, apenas os endereços definidos podem usar o token. Use Is not in para excluir partes de uma faixa autorizada. Há um limite importante: a restrição de IP não é aplicada ao endpoint de verificação do token, então um teste bem-sucedido nesse endpoint não prova que a chamada real será aceita a partir daquela rede.
Como testar sem vazar o segredo
O segredo aparece apenas uma vez após a criação. Salve-o diretamente em um gerenciador de segredos, variável protegida do CI ou cofre corporativo. Não cole o valor em repositórios, tickets, prints, prompts ou logs. Novos User API tokens usam o prefixo cfut_, que ajuda ferramentas de secret scanning a reconhecer vazamentos, mas detecção posterior não substitui armazenamento seguro.
Primeiro consulte o endpoint /user/tokens/verify com Authorization: Bearer e confirme status active. Depois teste o endpoint real com a operação de menor impacto disponível. Mostre apenas o código HTTP e metadados seguros no log; não ative debug que imprima o header Authorization.
- Injete o segredo pela variável CLOUDFLARE_API_TOKEN ou pelo cofre do ambiente.
- Envie o token no header Authorization usando o esquema Bearer.
- Confirme status active no endpoint oficial de verificação.
- Execute uma leitura permitida no recurso autorizado e outra em um recurso fora do escopo.
- Remova logs de headers antes de levar a integração para produção.
Token ativo, mas a API retorna 401 ou 403
Se o token não é aceito, confirme primeiro se ele está ativo, dentro da validade e enviado como Bearer. Usar a sintaxe antiga de e-mail mais Global API Key com um API token gera autenticação incorreta. Em seguida, compare a permissão exigida pelo endpoint com as permissões e os recursos escolhidos no token.
Um token pode estar ativo e ainda falhar porque recebeu Read quando a operação exige Edit, aponta para outra conta ou zona, vem de um IP não autorizado ou tenta conceder um acesso que o usuário criador não possui. Registre horário, endpoint, método e código de erro, mas não o segredo. Se várias integrações falharem ao mesmo tempo, consulte o Cloudflare Status antes de rotacionar tudo.
O que fazer se o token vazar ou o criador sair
Se o segredo for perdido ou comprometido, faça o roll do token ou crie outro. O roll gera um novo segredo, invalida o anterior e preserva as permissões existentes. Revise essas permissões antes de reutilizá-las, porque copiar um escopo excessivo apenas mantém o problema com outro valor.
Os novos formatos com prefixo e checksum permitem detecção mais confiável por secret scanners. Em repositórios públicos, o GitHub pode avisar a Cloudflare sobre um token exposto e a credencial pode ser revogada. Ainda assim, não espere a automação: interrompa o uso, rotacione, procure acessos indevidos e atualize cada consumidor conhecido.
Limitações e próxima ação útil
Este guia foi verificado em 8 de novembro de 2026. A reformulação facilita a revisão, mas não escolhe o escopo correto pelo administrador, não garante compatibilidade de Account API tokens e não impede que um segredo apareça em logs ou configurações. Restrições de IP também exigem atenção quando a automação usa runners com saída dinâmica.
A próxima ação é inventariar uma integração real e anotar endpoint, método, conta, zona, permissão e origem de rede. Crie um token novo com validade curta para o piloto, teste a leitura permitida e a negação fora do escopo, documente a rotação e só depois substitua a credencial antiga.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- User API tokens have a redesigned creation experienceCloudflare Changelog
- Create API tokenCloudflare Fundamentals
- Restrict tokensCloudflare Fundamentals
- TroubleshootingCloudflare Fundamentals
- Token formatsCloudflare Fundamentals
- Account API tokensCloudflare Fundamentals
- Roll tokensCloudflare Fundamentals
- Cloudflare StatusCloudflare