blog
Painéis

Token de API do cPanel: curl na UAPI sem senha

Token de API, curl na UAPI, tratamento de erro, rotação e revogação. E o caso em que a resposta certa é chave SSH com rsync, sem API nenhuma.

JR · · 10 min de leitura · 2 tabelas · 9 blocos de código

Resposta curta: Crie o token em cPanel > Security > Manage API Tokens e chame a UAPI em https://servidor:2083/execute/Modulo/funcao com o header Authorization: cpanel usuario:TOKEN. O token aceita data de expiração, mas não escopo por função: ele vale para a conta cPanel inteira, e limitar um terceiro exige outro mecanismo.

Neste artigo
  1. O que o token resolve e o que ele não resolve
  2. Criar o token em Security > Manage API Tokens
  3. Primeira chamada com curl: UAPI na 2083 e header Authorization
  4. Por que HTTP 200 não quer dizer que a chamada deu certo
  5. Token de usuário não tem escopo por função, e as saídas que existem
  6. Revogar é apagar da lista, não trocar a senha
  7. Quando backup por SSH e rsync é melhor que a API
  8. Checklist antes de colocar em produção

O que o token resolve e o que ele não resolve

Colocar a senha do cPanel dentro de um script cria três problemas ao mesmo tempo: a senha dá acesso à interface inteira, ela costuma ser a mesma usada por uma pessoa no navegador, e revogá-la quebra tudo que a usa. O token de API separa a credencial de máquina da credencial humana. Você cria, usa em curl, e apaga quando não precisa mais, sem tocar na senha de ninguém.

O que o token não resolve, e é a parte que quase nenhum tutorial escreve: na interface de tokens do cPanel não existe seleção de privilégios. A documentação oficial da interface Manage API Tokens descreve nome e data de expiração como os atributos do token, não uma lista de funções permitidas. Na prática, um token emitido para um fornecedor que só vai listar caixas de e-mail pode, com o mesmo header, chamar qualquer função UAPI disponível para aquela conta cPanel. Limitar o que o terceiro faz exige outro mecanismo, e a seção sobre escopo adiante compara as opções.

Não há medição própria nesta pauta. Tudo aqui é documental ou exemplo que você roda na sua conta; nenhum número de latência foi coletado.

Criar o token em Security > Manage API Tokens

Chegar na interface Manage API Tokens

No cPanel, grupo Security, item Manage API Tokens. A interface lista os tokens existentes com nome e data de expiração, e tem o botão de criação.

Nomear o token pensando no inventário, não na estética

O nome é o único metadado que sobra depois. Seis meses depois, teste e api não dizem quem usa nem o que quebra se você apagar. Um padrão que funciona: consumidor-finalidade-ano, por exemplo agencia-x-relatorio-email-2026. Se o token é de um fornecedor, o nome do fornecedor precisa estar ali, porque o dia da saída dele é o dia em que você vai procurar por esse nome.

Definir expiração e transformar esquecimento em falha segura

A criação permite marcar uma data de expiração. Use. Token sem expiração é token que sobrevive ao contrato, ao funcionário e à memória de quem criou. Para trabalho pontual (migração, auditoria, importação de dados), uma data curta, poucos dias, transforma o esquecimento em falha segura: o token morre sozinho.

Copiar o valor uma vez só e guardar fora da linha de comando

Depois de gerar, o valor do token é exibido na tela. Guarde no gerenciador de segredos, no secret do CI ou em arquivo com permissão restrita. Se perder, não há tela de "ver token": o caminho é gerar outro e revogar o antigo.

O valor não deve passar pela linha de comando em nenhum momento. Leia sem eco e grave direto no arquivo:

# armazenamento minimo em maquina de operacao
umask 077
mkdir -p ~/.config
read -rsp 'Cole o token: ' CPTOKEN; echo
printf 'CPTOKEN=%s\n' "$CPTOKEN" > ~/.config/cpanel-token.env
unset CPTOKEN
chmod 600 ~/.config/cpanel-token.env

O que vai para o histórico do shell aqui é printf ... "$CPTOKEN", não o segredo. Alternativa equivalente: abrir o arquivo com um editor sob umask 077 e colar lá dentro.

Antipadrão a evitar: export CPTOKEN='valor-literal' digitado no terminal. Isso grava o segredo em .bash_history, deixa o valor legível em /proc/<pid>/environ para qualquer processo do mesmo usuário e tende a vazar em env dentro de log de build. Nunca commite o arquivo. Se o token entrou num repositório, mesmo privado, trate como vazado e rotacione.

Primeira chamada com curl: UAPI na 2083 e header Authorization

O formato da chamada é direto. A URL é https://servidor:2083/execute/Modulo/funcao e a autenticação vai em um header com o esquema cpanel, o usuário da conta e o token separados por dois-pontos.

export CPUSER='usuario'
export CPHOST='servidor.exemplo.com.br'

# carrega CPTOKEN do arquivo, sem digitar o valor
set -a; . ~/.config/cpanel-token.env; set +a

curl -sS \
  -H "Authorization: cpanel ${CPUSER}:${CPTOKEN}" \
  "https://${CPHOST}:2083/execute/Email/list_pops"

Em máquina multiusuário, o header montado em -H ainda aparece no argv do processo, visível em ps. Para fechar essa brecha, use um arquivo de configuração do curl:

umask 077
printf 'header = "Authorization: cpanel %s:%s"\n' "$CPUSER" "$CPTOKEN" \
  > ~/.config/cpanel-curl.conf
curl -sS -K ~/.config/cpanel-curl.conf \
  "https://${CPHOST}:2083/execute/Email/list_pops"

Três detalhes que derrubam a primeira tentativa de muita gente:

Passar parâmetros sem errar o escape

Funções que recebem argumentos aceitam querystring. Com curl, o par -G mais --data-urlencode evita erro de escape em valores com espaço, acento ou &:

curl -sS -G -K ~/.config/cpanel-curl.conf \
  --data-urlencode "parametro=valor com espaco" \
  "https://${CPHOST}:2083/execute/Modulo/funcao"

O nome exato de cada parâmetro vem da documentação do módulo UAPI correspondente, não de adivinhação: função errada devolve erro, parâmetro errado costuma devolver sucesso com resultado vazio, que é bem pior de diagnosticar.

Por que HTTP 200 não quer dizer que a chamada deu certo

A UAPI devolve JSON com status, data, errors e messages. Uma chamada autenticada que falha na regra de negócio ainda pode voltar com código HTTP de sucesso e status zero. Script que testa só o exit code do curl vai reportar "backup criado" quando nada foi criado.

http=$(curl -sS -o /tmp/uapi.json -w '%{http_code}' \
  -K ~/.config/cpanel-curl.conf \
  "https://${CPHOST}:2083/execute/Email/list_pops")

echo "HTTP ${http}"
jq -r '.status, (.errors // [] | join("; "))' /tmp/uapi.json

A regra de ouro para automação: falhe se o HTTP não for 200 ou se .status não for 1, e registre .errors no log. Nunca registre o header Authorization junto: curl -v imprime o token em texto claro, e um log de CI é um arquivo que muita gente lê.

Sintoma Causa provável Como confirmar
HTTP 401, corpo com negativa de acesso header mal formado, usuário errado, token expirado ou revogado repetir com uma função sem parâmetros; conferir o token na lista de Manage API Tokens
Resposta em HTML, não em JSON a requisição não chegou na UAPI (proxy, WAF, porta errada) curl -v e olhar os headers de resposta e eventual redirecionamento
Erro de verificação de certificado hostname usado não é o do certificado do servidor openssl s_client -connect host:2083 e comparar o CN/SAN
HTTP 200 com status: 0 parâmetro ausente ou inválido, função indisponível no plano ler .errors e conferir o nome do parâmetro na doc do módulo
Conexão recusada ou pendurada só a partir do CI firewall de saída, ou IP de origem bloqueado por tentativas repetidas de autenticação testar do mesmo IP com curl -v; se houver proteção de força bruta no servidor, liberar o IP de saída

Esse último caso merece atenção em pipeline: um script que erra o token e repete em loop pode fazer o servidor bloquear o IP de saída do seu CI por tentativas de login, e aí até a chamada correta para de funcionar. Teste manualmente uma vez antes de colocar em cron.

Validacao de resposta UAPI em scriptChamada curlUAPI na 2083 com tokenHTTP igual a 200Se nao, falhar e logarCorpo e JSON validoHTML indica proxy ou porta erradastatus igual a 1Se nao, ler errorsSucesso realSo aqui o script segue
Exit code do curl nao basta: a UAPI devolve falha de negocio com HTTP 200 e status zero.

Token de usuário não tem escopo por função, e as saídas que existem

Como o token de usuário não carrega lista de permissões, a pergunta "como dou acesso só de leitura de e-mail para a agência" não tem resposta dentro da interface Manage API Tokens. Tem resposta fora dela.

Mecanismo Onde se cria Escopo por função Expiração Bom para
Token de API do cPanel cPanel > Security > Manage API Tokens Não: vale para a conta inteira Sim, data definida na criação automação sua, dentro da sua própria conta
Token de API do WHM WHM, fora da interface de tokens do cPanel O recorte por ACL vive no WHM; os atributos do token WHM não foram verificados nesta pauta não verificado aqui quando você tem WHM e precisa avaliar um recorte menor que a conta inteira, checando antes a documentação do WHM
Conta cPanel separada criação de nova conta Indireto: o escopo é a conta, com dados e domínios próprios via token da conta isolar dados de um fornecedor sem expor o site principal
Chave SSH com comando restrito ~/.ssh/authorized_keys da conta Sim, command= fixa o que a chave pode rodar sem campo na interface Manage SSH Keys, mas o OpenSSH 8.2+ aceita expiry-time="20260401" na própria linha do authorized_keys; revogar continua sendo remover a linha transferência de arquivo, backup, dump

A leitura honesta: se o consumidor do token é um terceiro, token de usuário cPanel dá a ele tudo que a conta pode fazer. Ou você aceita isso conscientemente, com expiração curta e revogação agendada, ou muda o mecanismo. Sobre o token do WHM, o que está escrito aqui é o caminho onde procurar, não uma afirmação sobre o comportamento dele: a fonte que esta pauta consultou cobre apenas a interface de tokens do cPanel.

Linha de authorized_keys com os dois controles juntos, para referência:

expiry-time="20260401",command="rsync --server --sender -vlogDtpre.iLsfxC . /home/usuario/public_html/",no-pty,no-agent-forwarding,no-port-forwarding ssh-ed25519 AAAA... backup off-site

Revogar é apagar da lista, não trocar a senha

Revogar é ação explícita e verificável: apagar o token na lista de Manage API Tokens. Não confie em efeito colateral de troca de senha como se fosse revogação; confie na lista ficar sem aquele nome.

Rotacionar o token sem janela de indisponibilidade

Como a conta pode ter mais de um token ativo, a troca é feita em sobreposição:

  1. Crie o token novo com nome versionado, por exemplo integracao-nf-2026-02, com data de expiração.
  2. Publique o valor novo no secret do consumidor (CI, servidor da aplicação, painel do fornecedor).
  3. Rode uma chamada de leitura com o token novo e confirme HTTP 200 e .status igual a 1.
  4. Acompanhe o consumidor por um ciclo completo de execução (um dia de cron, por exemplo).
  5. Apague o token antigo na interface e rode a mesma chamada com ele: o esperado agora é falha de autenticação. Se ainda funcionar, você apagou o token errado.

Runbook do dia em que o fornecedor sai

O roteiro é curto porque o inventário foi feito antes:

Se os tokens estivessem com nomes genéricos, esse roteiro viraria arqueologia. O nome é a diferença entre cinco minutos e uma tarde.

Rotacao de token em sobreposicaoCriar token novoNome versionado e expiracaoPublicar no consumidorSecret do CI ou aplicacaoTestar leituraHTTP 200 e status 1Observar um cicloUm dia de cron completoApagar o antigoConfirmar que passou a falhar
Dois tokens ativos ao mesmo tempo eliminam a janela de indisponibilidade na troca.

Quando backup por SSH e rsync é melhor que a API

Backup periódico não precisa de token, e essa é a recomendação contra o próprio interesse. Se o objetivo é levar arquivos e banco para fora do servidor todo dia, chave SSH mais rsync é mais simples de auditar, não depende de nenhuma função da API continuar existindo na próxima atualização do painel, e transfere de forma incremental.

# na maquina de destino, chave dedicada so para esse backup
ssh-keygen -t ed25519 -f ~/.ssh/backup_exemplo -C 'backup off-site'

# cole o conteudo de ~/.ssh/backup_exemplo.pub na conta cPanel,
# em SSH Access > Manage SSH Keys, e autorize a chave

# primeiro ciclo: sempre em simulacao, para ver o que seria apagado
rsync -az --delete --dry-run --itemize-changes \
  -e 'ssh -i ~/.ssh/backup_exemplo' \
  [email protected]:/home/usuario/public_html/ \
  /backups/exemplo/public_html/

--delete espelha a origem. Isso significa que exclusão acidental, ransomware ou defacement no servidor hospedado viram exclusão no seu backup no ciclo seguinte, e o que você tinha ontem deixa de existir. Espelho não é backup. Duas formas de manter o espelho sem perder o histórico:

# 1) mover o que seria apagado para uma pasta datada, em vez de destruir
rsync -az --delete \
  --backup --backup-dir="/backups/exemplo/apagados/$(date +%F)" \
  -e 'ssh -i ~/.ssh/backup_exemplo' \
  [email protected]:/home/usuario/public_html/ \
  /backups/exemplo/public_html/

# 2) destino versionado com hardlink: cada dia e um diretorio completo,
#    pagando espaco so pelo que mudou
rsync -az --delete \
  --link-dest=/backups/exemplo/diario/anterior \
  -e 'ssh -i ~/.ssh/backup_exemplo' \
  [email protected]:/home/usuario/public_html/ \
  "/backups/exemplo/diario/$(date +%F)/"

Reversão, no caso 1: copiar de volta o conteúdo de apagados/DATA. No caso 2: o diretório do dia anterior continua íntegro, basta apontar para ele. Se o destino estiver em filesystem com snapshot (ZFS, Btrfs, LVM), o snapshot antes do rsync cumpre o mesmo papel. E remova --dry-run só depois de ler a saída de --itemize-changes inteira, uma vez.

Para o banco, mysqldump remoto pelo mesmo túnel, sem arquivo intermediário no servidor de origem:

ssh -i ~/.ssh/backup_exemplo [email protected] \
  "mysqldump --single-transaction --quick usuario_wp" \
  | gzip -9 > /backups/exemplo/wp-$(date +%F).sql.gz

Em ambiente compartilhado, --single-transaction evita travar tabelas InnoDB durante o dump. Confirme antes se a conta tem acesso SSH liberado e qual é o nome real do banco. Verifique o dump gerado (gzip -t e um head no SQL) antes de confiar nele: arquivo de 20 bytes com mensagem de erro dentro também termina com exit code 0 na ponta do pipe.

Use a API quando o que você precisa é mudar estado do painel: criar caixa de e-mail, criar redirecionamento, criar subdomínio, consultar cota como parte de um fluxo. Para mover bytes de um lado para o outro, SSH resolve melhor.

Checklist antes de colocar em produção

Fonte da interface e dos atributos do token de usuário: Manage API Tokens in cPanel, consultada em 24/09/2026. Essa página não cobre token do WHM, por isso os atributos dele não são afirmados aqui. Os comandos acima são exemplos com host, usuário e token fictícios, para você reproduzir na sua própria conta.

Referências

  1. Documentação oficial (cpanel) — Manage API Tokens in cPanel. Consultado em 2026-09-24.
Leia também