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.

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
- O que o token resolve e o que ele não resolve
- Criar o token em Security > Manage API Tokens
- Primeira chamada com curl: UAPI na 2083 e header Authorization
- Por que HTTP 200 não quer dizer que a chamada deu certo
- Token de usuário não tem escopo por função, e as saídas que existem
- Revogar é apagar da lista, não trocar a senha
- Quando backup por SSH e rsync é melhor que a API
- 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:
- A porta é a de sessão do cPanel, 2083 com TLS. Não use 2082 em texto claro para carregar um token: quem estiver no caminho lê o header inteiro.
- O host precisa bater com o certificado. Chame pelo hostname do servidor, não pelo domínio do site que pode estar atrás de proxy ou CDN. Resolver o erro de certificado com
-ké desligar a única verificação que impede um interceptador de receber seu token. - O usuário do header é o dono da conta cPanel, e o token precisa ter sido criado dentro daquela conta. Token de uma conta não autentica outra.
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.
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:
- Crie o token novo com nome versionado, por exemplo
integracao-nf-2026-02, com data de expiração. - Publique o valor novo no secret do consumidor (CI, servidor da aplicação, painel do fornecedor).
- Rode uma chamada de leitura com o token novo e confirme
HTTP 200e.statusigual a 1. - Acompanhe o consumidor por um ciclo completo de execução (um dia de cron, por exemplo).
- 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:
- Abrir Manage API Tokens e apagar todo token cujo nome contenha o fornecedor.
- Verificar cada remoção com uma chamada que deve falhar.
- Remover as chaves SSH daquele fornecedor em Manage SSH Keys, se houver.
- Revisar contas de FTP e caixas de e-mail criadas para a integração.
Se os tokens estivessem com nomes genéricos, esse roteiro viraria arqueologia. O nome é a diferença entre cinco minutos e uma tarde.
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
- Token criado com nome que identifica consumidor e finalidade, e com data de expiração preenchida.
- Valor lido sem eco e gravado em secret ou arquivo
chmod 600, fora do repositório, fora do histórico do shell, nunca passado como literal na linha de comando. - Chamadas sempre em
httpsna 2083, sem-k, com hostname que bate com o certificado. - Em máquina compartilhada, header via
curl -Kem vez de-H, para o token não aparecer nops. - Script falha se HTTP não for 200 ou se
.statusnão for 1, e loga.errors. - Log do script não imprime o header
Authorization(cuidado comcurl -vem modo debug de pipeline). - Chamada de teste feita manualmente antes do cron, para não acumular falhas de autenticação a partir do IP do CI.
- Data de rotação anotada em calendário, com o passo de verificar que o token antigo passou a falhar.
- Se há
rsync --deleteno fluxo, existe--backup-dir,--link-destou snapshot no destino, e o primeiro ciclo foi rodado com--dry-run. - Se o consumidor é terceiro, decisão registrada: aceitar o escopo de conta inteira, ou avaliar token WHM com ACL, conta separada ou chave SSH restrita.
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
- Documentação oficial (cpanel) — Manage API Tokens in cPanel. Consultado em 2026-09-24.