A API do miniCP deixa sistemas externos (ERP, monitoramento, suporte, scripts de ativação) consultar usuários e domínios e, com o token de escrita, criar domínios e publicá-los no HAProxy.
A API fica em /api/v1 no mesmo endereço do painel. Ela vem desligada: só responde depois que você gera um token.
Tokens de leitura e de escrita
Existem dois tokens, cada um com uma finalidade.
| Token | O que permite | Quando usar |
|---|---|---|
| Leitura | Só consultas: usuários, domínios, situação no HAProxy, andamento de jobs. Nas variáveis de ambiente dos domínios (env), vê só os nomes, sem os valores. |
Painéis de monitoramento, ERP, ferramentas de suporte. |
| Escrita | Tudo o que o de leitura faz (inclusive os valores de env), mais criar, alterar e remover domínios e publicar ou tirar domínios do HAProxy. |
Automação de ativação de clientes, em sistemas de confiança. |
Com o token de leitura, uma operação de escrita responde 403 com a mensagem token somente leitura: use o token de escrita.
Atenção: os tokens da API são diferentes do token do cluster (usado pelo CmCP). Um não substitui o outro.
Versão mínima
| Recurso | Versão do miniCP |
|---|---|
| Consultas (token de leitura) | 2.55.0 |
| Escrita: domínios e HAProxy | 2.63.0 |
| Publicar um alias no HAProxy | 2.63.1 |
Token de leitura vê só os nomes de env |
2.66.0 |
Recomendamos 2.63.1 ou mais nova para usar a escrita. A versão do painel volta em toda resposta, no campo panel_version.
Gerar os tokens
- Entre no miniCP como administrador.
- Abra Configurações e fique na aba Geral.
- Na seção API, clique em Gerar token (token de leitura).
- Se precisar de escrita, clique em Gerar token de escrita e confirme.
- Copie o token do campo correspondente e guarde num cofre de senhas.
Para trocar um token, clique em Regerar. O token anterior para de funcionar na hora. Para desligar, clique em Remover: sem token de leitura nem de escrita, a API não responde a ninguém.
Restringir por IP
Na mesma seção há o campo de IPs permitidos.
- Informe os IPs ou redes que podem usar a API, separados por vírgula ou espaço. Exemplo:
203.0.113.10, 198.51.100.0/24. - Clique em Salvar IPs.
Com a lista preenchida, chamadas de outros endereços recebem 403 com ip nao permitido, mesmo com token válido. Lista vazia libera qualquer IP (com token). A lista vale para os dois tokens.
Com o painel atrás do HAProxy, o IP de quem chama é lido do fim do cabeçalho X-Forwarded-For (o valor acrescentado pelo balanceador). Um cabeçalho forjado por quem chama não burla a lista.
Dica: preencha a lista sempre que gerar o token de escrita. Quem tem esse token cria e remove domínios.
Como autenticar
Envie o token no cabeçalho Authorization:
MINICP=https://painel.exemplo.com.br:5000
TOKEN=seu_token
curl -s -H "Authorization: Bearer $TOKEN" "$MINICP/api/v1/"
O cabeçalho X-API-Token: seu_token também é aceito. O token não é aceito na URL, para não ficar gravado em logs.
A chamada a /api/v1/ devolve a lista de endpoints disponíveis.
Formato das respostas
Todas as respostas são JSON. As de sucesso têm "ok": true e estes campos fixos:
| Campo | Conteúdo |
|---|---|
ok |
true em caso de sucesso. |
server |
Nome do servidor que respondeu. |
panel_version |
Versão do miniCP. |
generated |
Data e hora da resposta. |
Os erros têm "ok": false e a mensagem em português no campo error. Veja a lista em API: erros e boas práticas.
Segurança
- Bloqueio por força bruta: cada chamada com token errado conta como tentativa de login falha. Cinco falhas em 15 minutos bloqueiam o IP por 15 minutos (resposta
429). As falhas do login no painel, da API e do token do cluster somam na mesma contagem, e o bloqueio vale para os três. - Auditoria: toda alteração feita pela API fica em Auditoria com o usuário
apie o IP de origem. - Regerar em caso de vazamento: se um token aparecer em log, chamado ou repositório, clique em Regerar e atualize o sistema que o usa.
- Use HTTPS: o token vai no cabeçalho de cada chamada. Acesse o painel por HTTPS.
/api/statusnão faz parte da API: esse endereço alimenta o Dashboard e exige sessão de administrador no painel. Não use em integrações; use os endpoints de/api/v1.