---
title: Chaves de API e escopos
description: Como os clientes criam chaves de API (prefixo vk_), escolhem escopos, limitam por IP e validade, e como os administradores as revisam e revogam.
url: https://nexcmp.com/pt/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Chaves de API e escopos {#api-keys-and-scopes}

> **Onde no portal:** API keys (`/api-keys`). **Onde no admin:** Customers › Customers › API keys (`/customers/apikeys`).

## O que faz {#what-it-does}

Uma **API key** permite que um script, job de CI, a [`cmp` CLI](https://nexcmp.com/pt/docs/developers/cmp-cli/) ou um assistente de IA ([MCP](https://nexcmp.com/pt/docs/developers/mcp/)) chame a [REST API](https://nexcmp.com/pt/docs/developers/api/) em nome de um cliente, apenas com as permissões (**escopos**) concedidas. As chaves de cliente começam com `vk_`. Elas podem ler e gerenciar serviços, mas **nunca** podem mexer com dinheiro ou com a própria conta.

## Requisitos {#requirements}

| Item | Requisito |
|---|---|
| Cliente | Uma sessão autenticada no portal (uma chave não pode criar ou editar outras chaves, e um administrador personificando um cliente também não pode). |
| Alternar | As chaves de API vêm ativadas por padrão. Se forem desativadas, as chamadas retornam 401 `api_keys_disabled`. |
| Dependências | Os escopos de um produto aparecem apenas quando esse produto está ativado no site. |

## Criar uma chave (cliente) {#create-a-key-customer}

1. Entre no portal e abra **API keys**.
2. Clique em **Create key**.
3. Preencha o formulário:

   | Campo | Regra |
   |---|---|
   | **Key name** | Obrigatório, até 60 caracteres ("deploy server", "backup script"). |
   | **O que esta chave pode fazer** | Marque os escopos necessários — pelo menos um. Uma chave somente leitura não deve receber nenhum escopo de gravação. Tenha cuidado com escopos que custam dinheiro ou excluem dados. |
   | **Expiry** | Nunca, 30 dias, 90 dias ou 1 ano (a API aceita de 1 a 3650 dias). |
   | **Permitir chamadas apenas destes IPs** | Um IP ou intervalo CIDR por linha, até 20 (IPv4 ou IPv6). Vazio significa qualquer IP. Fixe o IP do seu servidor sempre que puder. |

4. Confirme o formulário. A chave é exibida **uma única vez** em uma janela "Key created — shown ONCE". Copie-a e clique em **I saved the key**. Apenas um hash SHA-256 é armazenado, portanto nem mesmo um administrador pode lê-la novamente; se você perdê-la, revoque-a e crie uma nova.
5. O portal também exibe um comando `curl` pronto para testar a chave.


Uma chave se parece com `vk_` seguida por uma longa string aleatória. A lista exibe apenas os primeiros caracteres (por exemplo, `vk_a1b2c3d4`), os escopos, a validade, o último uso, a contagem de solicitações e o status (*Active*, *Expired*, *Revoked*).

### Edit, revoke, audit {#edit-revoke-audit}

- **Edit** altera o nome, os escopos, os IPs permitidos e a validade. Não é permitido durante uma sessão personificada.
- **Revoke** interrompe a chave imediatamente e não pode ser desfeito. A linha é mantida para que o log de uso continue disponível.
- **Key usage log** mostra comandos de gravação e cada erro dos últimos 60 dias: horário, requisição, chave, resultado e IP de origem.
- Uma conta pode ter no máximo **10 chaves ativas** por padrão.
- Chaves criadas por meio do CLI ou login MCP aparecem em **Connected apps & devices** e podem ser revogadas lá.

## Escopos {#scopes}

Os nomes dos escopos têm a forma `area:action`. Quais deles são oferecidos depende dos produtos que você ativou.

| Escopo | Permite |
|---|---|
| `catalog:read` | Ler planos e o catálogo. |
| `vm:read` | Ler VMs, métricas e faturas de VMs. |
| `vm:write` | Ações de energia, pequenas alterações, firewall, snapshots rápidos. |
| `vm:create` | **Criar VMs (gera custos).** |
| `vm:plan` | **Alterar plano ou redimensionar (gera custos).** |
| `vm:destroy` | **Excluir VMs.** |
| `vm:restore` | **Restaurar uma VM a partir de um snapshot (sobrescreve o disco).** |
| `vm:console` | Abrir tickets do console VNC. |
| `sshkey:read`, `sshkey:write` | Ler, adicionar e remover chaves SSH. |
| `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | Volumes de dados (criar e ampliar geram custos; destruir perde dados). |
| `backup:read`, `backup:write`, `backup:restore` | Backups (restaurar sobrescreve o disco). |
| `billing:read` | Carteira, faturas, histórico de pagamentos — **somente leitura**. |
| `bandwidth:buy` | **Comprar um complemento de largura de banda (gera custos).** |
| `account:read`, `account:write` | Perfil, visão geral, atividade, notificações; `account:write` apenas marca as notificações como lidas. |
| `apikey:read` | Listar as chaves da conta e o log de uso (não pode criar, editar ou revogar). |
| `apikey:self` | Implícito em todas as chaves: inspecionar a chave chamadora (`GET /v1/apikeys/self`). |
| `ticket:read`, `ticket:write` | Tickets de suporte. |
| `aff:read`, `transfer:read` | Programa de afiliados e transferências de serviços — somente leitura. |
| `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (criar e escalar geram custos; o kubeconfig é cluster-admin). |
| `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud. |
| `image:read`, `image:write` | Imagens de SO e ISO (o armazenamento é cobrado por hora). |
| `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (o segredo S3 é exibido apenas uma vez). |
| `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN e proxy IPv6 (os detalhes de conexão incluem senhas de proxy). |
| `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | Servidores dedicados (criar pedidos a partir da carteira; destruir reinstala o SO). |
| `shield:read`, `shield:write`, `shield:agent` | DDoS Shield, apenas quando esse módulo estiver ativado. |

Uma chamada fora dos escopos da chave retorna **403 `scope_required`**; um caminho que nenhuma chave pode chamar retorna **403 `endpoint_not_public`**.

### O que uma chave nunca pode fazer {#what-a-key-can-never-do}

Nenhum escopo abre: adicionar ou retirar dinheiro, alterar cartões ou recarga automática, alterar a senha, o e-mail ou a 2FA, excluir a conta, criar, editar ou revogar outras chaves. Estas ações sempre exigem um navegador conectado. Mesmo uma chave vazada não pode tocar no dinheiro ou na conta do cliente.

## Regras nas quais você pode confiar {#rules-you-can-rely-on}

| Regra | Detalhe |
|---|---|
| Vinculada ao site | Uma chave funciona apenas no site (domínio) onde foi criada. |
| Limites de taxa | Por chave e por conta: 120 e 300 requisições por minuto por padrão. |
| Idempotência | Operações que custam dinheiro ou não podem ser repetidas exigem um cabeçalho `Idempotency-Key`. |
| Quotas | Uma chave está sujeita às mesmas [quotas](https://nexcmp.com/pt/docs/billing/quotas/) do cliente. |
| Conta bloqueada | As chaves de um cliente bloqueado param de funcionar (403 `account_blocked`). |
| Auditoria | A revogação por um administrador é registrada no log de auditoria administrativa. |

## Visualização do administrador {#administrator-view}

1. Abra **Customers › API keys** (`/customers/apikeys`). A tabela mostra o nome da chave e os primeiros caracteres, proprietário, escopos, status, último uso (horário, contagem de solicitações, IP) e validade.
2. Filtre por site se você tiver revendedores. Pesquise por nome, ID ou início da chave.
3. Clique em **Revoke** para interromper uma chave ativa ou em **Log** para ver seu uso.
4. Os administradores **visualizam e revogam** chaves, mas não podem ler nem criá-las para os clientes.

![Lista de chaves de API de clientes do administrador com escopos, status, último uso e o botão Revoke](https://nexcmp.com/pt/docs/images/developers/api-keys-02-admin.webp)

## Verificar {#verify}

1. Crie uma chave apenas com o escopo `vm:read`.
2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` retorna a lista de VMs.
3. `curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX"` responde com 403 `scope_required`.
4. Revogue a chave; a primeira chamada agora responde com 401 `key_revoked`.

## Limites e notas {#limits-notes}

- A chave nunca mais é exibida. Trate-a como uma senha e armazene-a em um gerenciador de segredos ou segredo de CI.
- Prefira uma chave por script, escopos mínimos, validade curta e uma lista de permissão de IPs; faça a rotação criando uma nova chave e revogando a antiga.
- Chaves de login de dispositivos (CLI, MCP) têm validade padrão de 90 dias.
- Recursos excluídos ou transferidos não são afetados pela revogação de uma chave.

## Resolução de problemas {#troubleshooting}

| Sintoma | Causa | Correção |
|---|---|---|
| Erro `too_many_keys` (422) | O limite de chaves ativas (10 por padrão) foi atingido | Revogue uma chave antiga. |
| Erro `invalid_argument`: nenhum escopo escolhido | Nenhum escopo marcado | Marque pelo menos um escopo. |
| Erro `invalid_argument` em IPs permitidos | Uma entrada não é um IP ou intervalo, possui comprimento de prefixo incorreto ou mais de 20 entradas | Um IP ou CIDR por linha, por exemplo `203.0.113.0/24`. |
| A criação é recusada durante a impersonação | `impersonate_forbidden` | Peça ao cliente para criar a chave. |
| 401 `key_expired` | Data de validade ultrapassada | Crie uma nova chave. |
| 401 `key_ip_denied` | IP do chamador não está na lista de permissões | Adicione o IP ou limpe a lista. |
| 401 `api_keys_disabled` | Recurso desativado | Consulte o seu administrador (configuração `api_keys_enabled`). |