--- title: Admin API keys description: Crie e revogue chaves ak_ de admin para AI Agents e scripts: os oito escopos, validade, faixas de IP, rate limit, restrições e códigos de erro. url: https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Admin API keys {#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 {#what-it-does} 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. ::: info 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](https://nexcmp.com/pt/docs/developers/api-keys/)). 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 {#requirements} | 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 {#create-a-key} 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](#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). ![Caixa de diálogo de nova chave com nome, caixas de seleção de escopo, validade e intervalo de IP preenchidos](https://nexcmp.com/pt/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![Caixa de diálogo exibindo a nova chave uma vez com um botão Copiar e um aviso](https://nexcmp.com/pt/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## Escopos {#scopes} 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. | ::: tip 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 {#revoke-a-key} 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 {#what-a-key-can-never-do} 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 {#actions-that-need-your-confirmation} Elas só são concluídas após você aprovar uma pré-visualização (consulte [Two-step confirmation](#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 {#two-step-confirmation} 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: `. 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 {#rate-limit-and-ip-rules} - 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 {#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:/`. ![Aba Activity listando chamadas com status, cliente, ferramenta e IP](https://nexcmp.com/pt/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## Verificar {#verify} Teste uma chave somente leitura de qualquer máquina que esteja dentro do intervalo de IPs: ```bash 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: ```bash 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](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/). ## Erros {#errors} 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 {#limits-notes} - 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](https://nexcmp.com/pt/docs/configure-with-ai/oauth-connectors/)).