Admin API keys

Onde no admin: System › Settings › API & AI agents (/agent/keys), aba API keys. A mesma página possui as abas Connect an AI, Connected apps e Activity.

O que faz

Uma chave de API de admin (com prefixo ak_) permite que um cliente de IA ou script gerencie seu painel com exatamente as permissões concedidas. Ela funciona na API de admin em /v1/admin/ e no endpoint do MCP de admin /mcp/admin. Não funciona em nenhum outro lugar.

Não é o mesmo que as chaves de cliente

Os clientes criam chaves que começam com vk_ no portal do cliente (API keys and scopes). Elas alcançam apenas a API de cliente e /mcp. Uma chave ak_ é recusada na API de cliente, e uma chave vk_ é recusada na API de admin.

Requisitos

Item	Requisito
Função	Você deve estar conectado como admin. Chaves não podem criar outras chaves.
Demo	Em um painel de demonstração, a página é somente leitura: nenhuma chave pode ser criada ou revogada.
Acessibilidade	O cliente deve alcançar https://cloud.example.com/mcp/admin ou /v1/admin/... no seu painel (verifique seu firewall se usar restrições de IP).

Criar uma chave

1. Abra System › Settings › API & AI agents e permaneça na aba API keys.

2. Clique em Create new key.

3. Preencha o formulário:

   Campo	Regras
   Name	Até 60 caracteres, por exemplo "Claude Code no meu notebook".
   Escopos	Marque pelo menos uma. Consulte Scopes. Comece apenas com admin:read.
   Validade	1, 7, 30, 60 ou 90 dias. Padrão 30. Máximo 90. Não é possível criar uma chave sem validade.
   Intervalos de IP (opcional)	Um endereço IPv4 ou IPv6 ou CIDR por linha, por exemplo 203.0.113.0/24 ou 2001:db8::/48. No máximo 32. Deixe em branco para permitir qualquer IP.
   Chamadas por minuto	1 a 6000. Padrão 120.

4. Clique em Create key. Uma caixa exibe a chave uma única vez, por exemplo ak_XXXX. Copie agora: o NexCMP armazena apenas um hash e nunca mais poderá exibi-la.

5. Clique em I have saved the key. Abra a aba Connect an AI para obter comandos prontos para colar que já contêm a chave que você acabou de criar (apenas nesta página, até recarregá-la).

Escopos

Uma chave só pode usar as ferramentas e endpoints permitidos pelos seus escopos. Escopos de escrita não incluem acesso de leitura: uma chave que precisa ler e escrever também precisa de admin:read.

Escopo	O que ela permite
admin:read	Lê configurações, catálogo, clientes, faturamento e logs. Segredos nunca são retornados.
catalog:write	Planos, modelos de SO, cotas, códigos de desconto.
infra:write	Fontes de infraestrutura (CloudStack, Proxmox), zonas, servidores.
billing:write	Gateways de pagamento, moeda, faturas, saldos. Ações financeiras exigem confirmação.
customers:write	Clientes e revendedores.
settings:write	Configurações gerais, identidade visual, e-mail, páginas legais, módulos, notificações.
ai:write	O provedor de IA e os recursos de IA.
secrets:write	Grava senhas e chaves de API. Elas podem ser definidas, mas nunca lidas novamente.

Definir um segredo exige dois escopos

Qualquer chamada que transporte uma senha, chave de API ou valor de token (uma senha SMTP, uma chave de pagamento, um token de bot do Telegram, uma chave de provedor de IA, credenciais do CloudStack ou Proxmox) precisa de secrets:write e o escopo da área (por exemplo, settings:write para SMTP). Se preferir digitar os segredos você mesmo, deixe secrets:write desativado e insira-os no painel administrativo.

Revogar uma chave

1. Encontre a chave na tabela (status Active, Expired ou Revoked; Last used mostra a hora e o cliente).
2. Clique em Revoke e confirme.

A chave para de funcionar imediatamente. A revogação é permanente; crie uma nova chave se precisar de outra.

O que uma chave nunca pode fazer

Uma chave nunca pode alcançar estas áreas, independentemente de seus escopos. Elas exigem que você esteja conectado como administrador.

• Criar ou alterar usuários administradores, 2FA e segurança de login, sessões de admin e os tokens de API do admin.
• Criar, listar ou revogar chaves de admin, conexões OAuth e contas de IA, ou usar o AI Console.
• Fazer backup ou restaurar o painel, atualizá-lo ou alterar sua licença.
• Entrar como cliente ou revendedor, abrir o console de um cliente, ler credenciais de VM ou kubeconfig, definir chaves SSH, ou enviar ou redefinir senhas.
• Alterar módulos de rede e roteamento (BGP, FRR, RTBH, XDP, interfaces, rotas estáticas e de política, NAT) ou agentes externos e integração de portal. Estes são somente leitura.
• Alterar configurações como demo_*, admin_*, listas de hosts, passkey, reautenticação e segredos de captcha.

Tudo o que não estiver coberto por uma regra é fechado por padrão para gravações e legível com admin:read para leituras.

Ações que exigem sua confirmação

Elas só são concluídas após você aprovar uma pré-visualização (consulte Two-step confirmation):

• Alterar o saldo de um cliente ou a carteira de um revendedor, desembolsar dinheiro, registros de cobrança, a taxa de câmbio.
• Alterar preços (preços de planos, criação em massa de planos, preços de imagens e armazenamento) e criar códigos de desconto ou de saldo.
• Salvar credenciais de gateway de pagamento ou a conexão com o CloudStack.
• Excluir qualquer coisa, bloquear ou excluir um cliente, alterar os limites de um cliente, suspender ou fechar um revendedor.
• Agir em servidores de clientes ou criar um servidor pago para um cliente.
• Alterar chaves de todo o site, configurações de segurança de login ou configurações de pagamento por meio das configurações gerais.

Confirmação em duas etapas

Quando uma chamada exige confirmação, nada muda ainda. A resposta é HTTP 428 com confirm_required, um confirm_token, um preview (método, caminho, motivo, os novos valores e, quando disponíveis, os valores atuais) e expires_in: 300.

1. O cliente mostra a pré-visualização para você.
2. Após você aprovar, ele repete a mesma requisição (mesmo método, caminho e corpo) com o cabeçalho X-Confirm-Token: <confirm_token>. As ferramentas de MCP aceitam o argumento confirm_token em vez disso.
3. O token funciona uma vez e expira após 5 minutos.

Chaves criadas dentro do painel para o AI Chat só podem ser confirmadas na tela: a resposta diz confirm_in: "ui" e um cartão de confirmação aparece no painel administrativo. A IA não pode aprová-lo.

Regras de limite de taxa e IP

• Acima do limite por minuto, uma chamada retorna rate_limited (HTTP 429) com Retry-After: 60.
• Com intervalos de IP definidos, chamadas de qualquer outro endereço retornam ip_not_allowed (HTTP 403).

Activity log

A aba Activity lista todas as chamadas feitas com uma chave, da mais recente para a mais antiga: horário, chave, cliente, modo de envio (http, mcp, chat, cli, confirm, preview), método e caminho, ferramenta, status HTTP, IP e os detalhes (mascarados). Você pode pesquisar por caminho, ferramenta ou nome da chave, exibir apenas erros (HTTP 400 ou superior) ou apenas chamadas aguardando confirmação (428 ou superior), e limitar o período para a última hora, 24 horas ou 7 dias. NexCMP mantém as 200,000 entradas mais recentes. As alterações feitas por meio de uma chave também aparecem em Logs › Admin actions sob o nome ak:<admin>/<key name>.

Verificar

Teste uma chave somente leitura de qualquer máquina que esteja dentro do intervalo de IPs:

curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"

Você obtém uma lista JSON das ferramentas permitidas pelos seus escopos. Execute uma:

curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'

O horário de Last used da chave é atualizado e a chamada aparece em Activity. A lista completa de ferramentas e uma descrição OpenAPI (/v1/admin/openapi.json) estão descritas em Connect an AI client.

Erros

Os erros são em JSON: {"error": {"code": "...", "message": "..."}}.

HTTP	code	Significado	Correção
401	invalid_key	A chave está ausente, malformada ou desconhecida. Também retornado quando uma chave ak_ é usada em um caminho que não é de administração.	Verifique a chave; use-a apenas em /v1/admin/ e /mcp/admin.
401	key_expired	A validade da chave expirou.	Crie uma nova chave.
401	key_revoked	A chave foi revogada.	Crie uma nova chave.
403	ip_not_allowed	O IP do chamador está fora dos intervalos de IP da chave.	Faça a chamada a partir de um IP permitido ou crie uma chave com o intervalo correto.
403	local_only_key	Uma chave criada para AI Chat ou para a CLI do servidor foi usada de outra máquina.	Essas chaves funcionam apenas no próprio servidor do painel.
403	insufficient_scope	A chave não possui um escopo; a resposta inclui required_scope.	Crie uma chave com esse escopo.
403	forbidden_for_keys	O endpoint, ou a configuração que você tentou alterar, está fechado para chaves.	Faça isso na administração.
403	demo_read_only	O painel está no modo de demonstração e a chamada realiza gravações.	Use um painel que não esteja em modo de demonstração.
403	confirm_in_ui	Esta ação deve ser confirmada na tela na administração.	Aprove o cartão de confirmação.
428	confirm_required	Uma prévia está pronta; nada foi alterado. Inclui confirm_token.	Exiba a prévia e repita com X-Confirm-Token.
409	confirm_expired	O token tem mais de 5 minutos.	Envie a solicitação novamente para obter uma nova prévia.
409	confirm_mismatch	O token pertence a uma solicitação diferente (método, caminho ou corpo diferem).	Repita exatamente a mesma solicitação.
409	confirm_invalid	Token desconhecido ou já utilizado.	Envie a solicitação novamente para obter uma nova prévia.
429	rate_limited	Muitas chamadas neste minuto.	Aguarde Retry-After.
400	invalid_path	O caminho contém sequências proibidas.	Use um caminho simples.
413	too_large	O corpo tem mais de 10 MB.	Envie menos dados.
400	invalid_argument	Um argumento de ferramenta está ausente, é desconhecido ou tem o tipo incorreto; a mensagem o identifica.	Corrija o argumento.

Limites e notas

• Mantenha as chaves de curta duração e escopo restrito. Prefira uma chave por cliente para poder revogar uma única chave.
• Uma chave é tão poderosa quanto seus escopos. secrets:write mais billing:write é a combinação mais sensível; ações financeiras ainda param em uma prévia.
• Chaves criadas automaticamente (para o AI Chat, a CLI do servidor) duram apenas alguns minutos e funcionam somente a partir do servidor do painel.
• Para cortar o acesso de um cliente de IA imediatamente, revogue sua chave. As conexões OAuth são revogadas na aba Connected apps (OAuth connectors).