Chaves de API e escopos

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

O que faz

Uma API key permite que um script, job de CI, a cmp CLI ou um assistente de IA (MCP) chame a REST 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

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)

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

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

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

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

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.

Verificar

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

• 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

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