# 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.

> 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.

João Rizzon · 2026-09-26 · Painéis

---

## 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](https://docs.cpanel.net/cpanel/security/manage-api-tokens-in-cpanel/) 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:

```bash
# 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.

```bash
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`:

```bash
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 `&`:

```bash
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.

```bash
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 200` e `.status` igual 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.

```bash
# 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' \
  usuario@servidor.exemplo.com.br:/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:

```bash
# 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' \
  usuario@servidor.exemplo.com.br:/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' \
  usuario@servidor.exemplo.com.br:/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:

```bash
ssh -i ~/.ssh/backup_exemplo usuario@servidor.exemplo.com.br \
  "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 `https` na 2083, sem `-k`, com hostname que bate com o certificado.
- Em máquina compartilhada, header via `curl -K` em vez de `-H`, para o token não aparecer no `ps`.
- Script falha se HTTP não for 200 ou se `.status` não for 1, e loga `.errors`.
- Log do script não imprime o header `Authorization` (cuidado com `curl -v` em 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 --delete` no fluxo, existe `--backup-dir`, `--link-dest` ou 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](https://docs.cpanel.net/cpanel/security/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.

