Skip to main content

Melhores práticas de prevenção de vazamento de chave de API

Previna vazamentos de chaves de API em três camadas: encurtar o tempo de exposição da credencial, restringir o escopo de permissões e configurar alertas com mitigação de perdas, abrangendo chaves de API temporárias, rotação regular, listas de permissões de IP, conexões privadas, alertas de orçamento e alertas de monitoramento de modelos.

Visão geral

Uma chave de API é a credencial usada para chamar os serviços de modelo do Alibaba Cloud Model Studio. Depois de vazar, qualquer pessoa que a obtenha pode chamar os modelos dentro do escopo de autorização da chave e consumir sua cota. O impacto de um vazamento pode ser decomposto em quatro fatores: probabilidade de vazamento, tempo de exposição, escopo de permissões por chamada e duração da anomalia. A probabilidade de vazamento é reduzida pelas práticas básicas presentes em toda esta página, e os outros três fatores são reduzidos pelas três camadas a seguir:

Camada

Fator reduzido

Medidas principais

Encurtar o tempo de exposição

Tempo de exposição

Chaves de API temporárias para clientes, exibição única com armazenamento controlado, rotação regular e revogação na saída de pessoal

Restringir o escopo de permissões

Escopo de permissões por chamada

Uma chave por negócio, isolamento por workspace, lista de permissões de IP e escopo de modelos, conexões privadas

Alertas e mitigação de perdas

Duração da anomalia

Alertas de orçamento com parada automática, alertas de monitoramento de modelos, detecção de riscos da plataforma

Práticas básicas aplicáveis às três camadas:
  • Aplicativos leem credenciais de variáveis de ambiente ou de um serviço de gerenciamento de chaves, em vez de codificá-las diretamente; configure a varredura de informações confidenciais no CI/CD (com ferramentas de varredura de credenciais como o gitleaks), cobrindo padrões de chaves de API.
  • Mantenha um registro de chaves: comece com uma tabela básica de IDs de chaves, finalidades, responsáveis e datas da última rotação e, aos poucos, acrescente região, workspace, escopo de permissões e orçamento; nunca armazene chaves completas no registro.
  • Restrinja as permissões de gerenciamento de chaves (criar, visualizar, editar, excluir) aos administradores que delas necessitam.

Encurtar o tempo de exposição da credencial

Armazene chaves de API permanentes com segurança

Uma chave de API recém-criada é exibida por completo apenas uma vez, no momento da criação; depois que a caixa de diálogo é fechada, o texto completo não pode mais ser visualizado nem copiado. Se você não a salvou, só é possível redefinir ou recriar a chave; consulte Obter uma chave de API. Após a criação, armazene a chave completa diretamente em um repositório de credenciais controlado (um serviço de gerenciamento de chaves ou o gerenciamento de segredos da sua plataforma de implantação), sem fazê-la transitar por capturas de tela, e-mails, ferramentas de chat ou documentos comuns; o valor mascarado na lista serve apenas para identificação e comparação. Nunca coloque chaves de API permanentes nos seguintes locais:
  • Scripts de navegador, artefatos de build do frontend e pacotes de aplicativos móveis
  • Repositórios de código públicos ou compartilhados (apenas adicionar .gitignore não remove credenciais de commits históricos)
  • Saídas de notebooks e códigos de exemplo
  • Capturas de tela e gravações de tela
  • Tickets de suporte, chats em grupo e documentos online
  • Prompts, bases de conhecimento e contextos de agentes
  • URLs de requisição e parâmetros de consulta
  • Logs de acesso e pilhas de exceção
  • Plug-ins de terceiros e serviços de retransmissão de modelos (serviços que encaminham suas chamadas de modelo)
  • Ambientes compartilhados, arquivos de configuração expostos externamente, imagens e backups
Para depuração local, defina a variável de ambiente com entrada oculta para evitar que o texto claro fique no histórico de comandos:
read -r -s -p "Enter API key: " DASHSCOPE_API_KEY
printf '\n'
export DASHSCOPE_API_KEY
Este exemplo se aplica a Linux/macOS.
Variáveis de ambiente evitam a codificação fixa no código, mas não são armazenamento criptografado: credenciais ainda podem vazar por diagnósticos de processos, configurações de contêiner, despejos de memória ou exportações de operações; durante a depuração, evite opções como set -x, que exibem variáveis confidenciais. Em produção, use um serviço de gerenciamento de chaves ou a injeção de segredos da plataforma de implantação.
Se você já forneceu uma chave de API a um serviço de retransmissão de modelos não confiável ou a um plug-in de terceiros, pare de entregar novas chaves a ele, mude para a API oficial ou uma integração confiável no lado do servidor e faça a rotação das chaves já entregues.

Use chaves de API temporárias em cenários no lado do cliente

Navegadores, aplicativos móveis e mini programas não conseguem manter credenciais confidenciais de forma confiável. Nesses cenários, faça com que um backend autenticado emita chaves de API temporárias para o frontend usar em chamadas diretas:
  1. Mantenha a chave de API permanente apenas no seu próprio servidor e nunca a entregue a nenhum cliente.
  2. Quando o frontend precisar chamar um modelo, solicite primeiro uma chave temporária ao seu backend.
  3. O backend chama a API de geração de chave de API temporária e retorna ao frontend uma chave st- de curta duração.
  4. O frontend chama o Model Studio diretamente com a chave st-.
Uma chave de API temporária é válida por 60 segundos por padrão; é possível definir de 1 a 1.800 segundos por meio de expire_in_seconds (configure a duração mais curta que a tarefa exigir e não use o valor máximo incondicionalmente). Ela expira automaticamente e não pode ser excluída antecipadamente; ela herda todas as permissões da chave de API permanente que a emitiu, portanto restrinja primeiro a chave permanente emissora quando forem necessárias menos permissões. A API de emissão é chamada pela OpenAPI com a chave permanente; valide as permissões de quem chama e limite a frequência de emissão para não transformá-la em um distribuidor público de credenciais. Para detalhes da API, consulte Gerar uma chave de API temporária.

Faça a rotação regular das chaves e revogue-as na saída de pessoal

Chaves de validade longa configuradas em códigos ou agentes acumulam exposição com o tempo e devem passar por rotação regularmente:
  1. Crie uma nova chave e reconfigure permissões e orçamento conforme as necessidades atuais.
  2. Atualize as referências de credenciais nos serviços do negócio.
  3. Verifique se a nova chave funciona corretamente.
  4. Exclua a chave antiga e confirme que ela não consegue mais iniciar chamadas.
  5. Atualize o registro de chaves.
Uma nova chave não herda automaticamente as permissões e o orçamento da antiga; é necessário reconfigurá-los. Quando pessoas saem da empresa ou um negócio é encerrado, você deve inventariar separadamente e excluir ou fazer a rotação das chaves dessas pessoas: chaves de API criadas em 25 de março de 2026 ou depois não são excluídas junto com o usuário RAM ao qual pertencem e continuam utilizáveis (a regra é relevante apenas quando a chave pertence a uma subconta RAM); portanto, não presuma que as credenciais foram revogadas só porque o usuário RAM foi excluído; consulte Validade da chave de API. Se várias chaves estiverem armazenadas no mesmo servidor suspeito de comprometimento, na mesma configuração pública, no mesmo repositório de código ou no mesmo ambiente de terceiros, faça a rotação de todas as credenciais potencialmente afetadas e corrija o ambiente: nem substitua todas as chaves de forma indistinta, nem trate apenas de uma chave ignorando a exposição compartilhada do ambiente. Prática avançada: hospede o texto claro das chaves em um serviço de gerenciamento de chaves (KMS), faça os aplicativos recuperá-las pelo nome da credencial e use a capacidade de rotação de chaves do KMS para atualizá-las periodicamente.

Restrinja o escopo de permissões da credencial

Uma chave por negócio e isolamento por workspace

Atribua chaves de API independentes a aplicativos e ambientes distintos (produção, testes e depuração pessoal): isso reduz o impacto do vazamento de uma única chave e facilita localizar problemas e fazer a rotação por chave. Quando você precisar de isolamento de permissões, de controle refinado de acesso a modelos ou de contabilidade de custos independente, atribua ao negócio um workspace não padrão (um workspace é um contêiner do Model Studio que isola permissões e custos; toda conta já tem um workspace padrão); o escopo básico de chamadas de uma chave é restringido pelo workspace ao qual ela pertence; consulte Gerenciamento de permissões. Além disso, restrinja as permissões de gerenciamento de chaves aos administradores necessários; contas que podem fazer login no console para gerenciar credenciais devem seguir o princípio do menor privilégio e habilitar a autenticação multifator conforme as exigências da organização.

Configure a lista de permissões de IP e o escopo de modelos

Depois de definir a permissão de uma chave de API como Personalizada no painel de criação ou edição da chave, você pode restringir ainda mais o escopo de chamadas dela:
  • Lista de permissões de IP: permita apenas os IPs ou blocos CIDR de saída públicos realmente usados pelo negócio, com no máximo 20 entradas (use um serviço como curl ifconfig.me para descobrir seu IP de saída público). Todos os endereços IPv4 são permitidos por padrão; apenas criar a chave não significa que as restrições de origem estão em vigor. Ao chamar por NAT, proxy ou gateway, informe o endereço de saída público que o Model Studio realmente vê, e não o endereço de intranet do servidor.
  • Escopo de modelos: uma vez habilitado, a chave só pode chamar os modelos selecionados (até 30, limitados pelos modelos autorizados no workspace), impedindo que chaves vazadas sejam usadas em modelos de alto custo.
Depois de configurar, verifique se a restrição entrou em vigor: apenas as redes e os modelos permitidos podem ser chamados, e os não autorizados não; não exiba a chave completa durante a verificação. Para o ponto de entrada e as regras completas, consulte Permissões de chave de API.
Uma lista de permissões de IP não substitui a confidencialidade da credencial: pessoas ou hosts comprometidos que consigam iniciar chamadas pela mesma rede de saída ainda podem fazer mau uso de uma chave vazada.

Chame por meio de uma conexão privada

Para cenários com requisitos rigorosos de segurança de rede, você pode estabelecer uma conexão privada (PrivateLink) entre sua VPC e o Model Studio: as chamadas não passam pela rede pública, de modo que invasores externos sem conectividade de rede não conseguem chamar o serviço mesmo que a chave vaze. Para o método de configuração, consulte Acessar as APIs do Model Studio por meio de uma rede privada.

Configure alertas e mitigação de perdas

Alertas de orçamento e parada automática

Defina orçamentos mensais e limites de alerta para a conta, um workspace ou uma única chave de API; priorize orçamentos independentes para chaves de alto risco, como as de desenvolvimento e testes, demonstrações e integrações de terceiros. Quando o gasto atinge o limite e quando o orçamento se esgota, notificações são enviadas por mensagens internas do site, SMS, e-mail ou bots; após habilitar "parar imediatamente quando o orçamento for atingido", o serviço restringe as chamadas pay-as-you-go dessa dimensão e retorna 429. Para o método de configuração, consulte Gerenciamento de orçamento.
A parada imediata quando o orçamento é atingido entra em vigor com atraso, e os encargos incorridos durante o atraso continuam sendo cobrados; chamadas da parte excedente do throughput pré-provisionado (PTU) e de aplicativos ainda não têm suporte à parada automática. Para negócios críticos em produção, não habilite a parada automática; prefira alertas combinados com tratamento controlado.

Alertas de monitoramento de modelos

O monitoramento de modelos agrega por workspace o número de chamadas, o uso de tokens, o número de falhas e a taxa de falhas, oferece filtragem por chave de API e permite criar regras de alerta com base em modelos de alerta predefinidos ou personalizados, notificando contatos ou grupos de contatos. Configure alertas de pico de volume ou de número de chamadas para chaves de alto risco: as anomalias ficam visíveis em minutos após as chamadas ocorrerem, e disparos fora do horário de trabalho exigem intervenção manual. A primeira configuração de alerta exige autorizar antes a função de serviço do Cloud Monitor na entrega de dados; para o método de configuração, consulte Alertas.

Detecção de riscos pela plataforma

A plataforma examina periodicamente ambientes públicos, como repositórios de código abertos, para identificar chaves de API vazadas e notificar você proativamente; os canais concretos dependem do que está habilitado (podem incluir SMS, e-mail e mensagens internas do site). Ela também identifica comportamentos anômalos, como logins de IPs incomuns, picos de tráfego fora do horário e aumentos anormais de custos. A detecção e os alertas de riscos da plataforma são capacidades de detecção de anomalias e de aviso antecipado oferecidas proativamente pela plataforma para melhorar a experiência de uso; não estão dentro do escopo de serviços acordado no SLA; devido à complexidade dos cenários de risco, não há compromisso de cobertura absoluta dos alertas, e a identificação e a entrega dos alertas também podem sofrer atrasos. A guarda segura e o uso em conformidade de credenciais como chaves de API são de sua responsabilidade; tome como linha de defesa principal os alertas de orçamento, os alertas de monitoramento de modelos e a rotação regular configurados por você mesmo; não receber alertas da plataforma não significa que não há risco de vazamento. Ao identificar um vazamento suspeito ou receber um alerta, localize e trate o problema seguindo Investigação de vazamento de chave de API.

Checklist antes da entrada em produção

Desenvolvedores individuais e equipes pequenas podem começar pelo mínimo: definir orçamento com notificações de alerta para a chave, manter a credencial apenas em variáveis de ambiente e fazer a rotação regularmente. O checklist completo é o seguinte:
  • Produção, testes e integrações de terceiros não compartilham a mesma chave de API; os responsáveis e as finalidades de cada chave estão claros.
  • Região, workspace, escopo de modelos e IPs de saída das requisições foram verificados, com permissões cobrindo apenas o escopo necessário.
  • Chaves permanentes ficam armazenadas apenas em backends controlados e nunca entram em clientes, código-fonte, prompts, documentos compartilhados ou logs.
  • As chaves não foram entregues a serviços de retransmissão de terceiros não confiáveis ou a ambientes de plug-ins; se foram, a entrega foi interrompida e as chaves passaram por rotação.
  • As credenciais são injetadas por variáveis de ambiente ou por segredos; arquivos confidenciais e artefatos de build não contêm texto claro.
  • Cenários de chamada direta pelo cliente usam chaves de curta duração emitidas por um backend autenticado, e a chave permanente emissora teve as permissões restritas.
  • As novas chaves foram armazenadas sob controle; as chaves antigas, as chaves ociosas e as chaves de pessoas que saíram foram revisadas.
  • Orçamentos e alertas nos níveis de conta, workspace e chave foram configurados, com canais de notificação e responsáveis definidos.
  • O impacto na disponibilidade e o atraso de efetivação da parada imediata quando o orçamento é atingido foram avaliados.
  • Os procedimentos de rotação e de resposta a vazamentos estão definidos; as etapas de investigação estão descritas em Investigação de vazamento de chave de API.

Perguntas frequentes

Não. Uma chave de API temporária herda todas as permissões da chave de API permanente que a emitiu; apenas o período de validade é mais curto. Para ter menos permissões, restrinja primeiro a chave de API permanente emissora.
Sim. Uma lista de permissões de IP restringe apenas a rede de origem das chamadas; uma chave vazada dentro da mesma rede de saída ainda pode ser usada indevidamente. Combine-a com o menor privilégio, alertas de orçamento e rotação regular.
Pare de entregar novas chaves a esse serviço, faça a rotação das chaves entregues e mude para a API oficial ou uma integração confiável no lado do servidor. Para tratar chaves vazadas, consulte Investigação de vazamento de chave de API.