Boas práticas de gestão de chaves de API para produtos de IA (checklist de 2026)

Boas práticas de gestão de chaves de API para produtos de IA (checklist de 2026)

As boas práticas de gestão de chaves de API se resumem a cinco pontos: manter as chaves no servidor e fora do código, dar a cada ambiente e carga de trabalho uma chave própria com escopo restrito, armazenar as chaves em um gerenciador de segredos, fazer a rotação e a revogação em um cronograma testado e monitorar o uso sem nunca registrar a própria chave nos logs. Para produtos de IA, os riscos são maiores do que na maioria das APIs, pois uma chave de modelo vazada pode gerar uma conta alta em poucas horas e também autorizar o acesso a prompts, arquivos e chamadas de ferramentas.

Este guia transforma esses princípios em um checklist que equipes de plataforma, segurança e produtos de IA podem aplicar. Ele aborda o ciclo de vida das chaves, um modelo de inventário, rotação sem indisponibilidade, proteções de CI/CD, um procedimento de resposta a incidentes e código para gerar, armazenar e verificar chaves. As fontes incluem a folha de referência da OWASP sobre gestão de segredos, as boas práticas do Google Cloud para chaves de API e a documentação do GitHub sobre detecção de segredos, todas consultadas em 27 de outubro de 2026.

Boas práticas de gestão de chaves de API: checklist rápido

#	Boa prática	O que evita
1	Nunca inclua chaves diretamente no código-fonte, em notebooks ou em aplicativos cliente	Vazamentos pelo histórico do Git, por bundles do navegador e por binários de aplicativos móveis
2	Mantenha as chaves dos provedores no servidor; forneça aos clientes tokens de sessão de curta duração	A extração da sua chave de um dispositivo por usuários ou malware
3	Use uma chave por ambiente, aplicação e membro da equipe	Que um vazamento derrube tudo quando você revogar a chave
4	Aplique as restrições mais rigorosas disponíveis: APIs, modelos, IPs, cotas	Que chaves roubadas possam ser usadas para qualquer finalidade
5	Armazene as chaves em um gerenciador de segredos, não em tickets, chats ou wikis	Cópias que você não consegue localizar ou substituir durante a rotação
6	Mantenha um inventário de chaves com responsável, carga de trabalho e data de rotação	Que a rotação interrompa consumidores desconhecidos
7	Faça a rotação em um cronograma com uma janela de sobreposição e depois revogue a chave antiga	Chaves de longa duração que continuam válidas após a saída de funcionários e fornecedores
8	Exclua as chaves que você não usa mais	Chaves esquecidas com permissões ativas
9	Ative a detecção de segredos e a proteção de push	Que chaves cheguem a um repositório público ou compartilhado
10	Nunca registre chaves ou cabeçalhos de autorização nos logs; registre um ID ou uma versão da chave	Vazamentos de segredos por logs, rastreamentos e relatórios de erros
11	Defina limites de gastos e alertas de uso incomum	Contas inesperadas causadas por uma chave roubada ou usada sem controle
12	Tenha um procedimento de incidentes que priorize a revogação	Exposição prolongada enquanto as equipes discutem se a chave vazada foi usada

O restante deste guia explica como implementar cada prática em cargas de trabalho de IA, nas quais uma chave faz mais do que autenticar: ela autoriza um caminho de dados para prompts, documentos e saídas de modelos.

O ciclo de vida de uma chave de API

A OWASP recomenda gerenciar os segredos ao longo de todo o ciclo de vida: criação, rotação, revogação e expiração, com auditoria em cada etapa (folha de referência da OWASP sobre gestão de segredos). Para uma chave de API de IA, esse ciclo funciona assim:

Etapa	Ação do responsável	Evidência a manter
Solicitação	Justificar a carga de trabalho, o ambiente e os modelos necessários	Ticket ou entrada no inventário
Criação	Gerar a chave no console ou na API do provedor com um nome descritivo	ID da chave, data e hora de criação, criador
Restrição	Limitar modelos, APIs, redes e orçamento	Configurações de restrição
Armazenamento	Salvar diretamente em um gerenciador de segredos; nunca colar em outro lugar	Caminho do segredo e política de acesso
Entrega	Injetar em tempo de execução na única carga de trabalho que precisa dela	Vínculo com o deployment
Monitoramento	Acompanhar requisições, tokens, gastos e data e hora do último uso	Painel de uso e alertas
Rotação	Criar uma substituta, migrar o uso e verificar	Registro da rotação
Revogação	Invalidar no provedor e confirmar um 401	Data e hora da revogação e resultado do teste

As cinco fronteiras que uma chave de IA pode atravessar

Comece mapeando os pontos pelos quais um segredo ou os dados cujo acesso ele autoriza podem transitar. A maioria das falhas ocorre porque as equipes protegem a chave do provedor, mas deixam passar uma destas fronteiras adjacentes.

Fronteira	Falha típica	Controle necessário
Do cliente para a aplicação	Uma chave de provedor é embutida em um bundle do navegador, binário de aplicativo móvel, aplicativo desktop ou extensão	Mantenha as chaves dos provedores no servidor; emita credenciais de usuário ou sessão de curta duração para os clientes
Da aplicação para o gateway	Todos os serviços compartilham uma chave sem restrições	Use identidades de carga de trabalho, tokens de gateway com escopo definido, cotas e uma política explícita de rotas
Do gateway para o provedor	Uma credencial pode acessar todos os modelos, projetos ou ambientes	Separe as chaves por provedor, ambiente, carga de trabalho e nível de risco quando houver suporte
Da requisição para os logs	Cabeçalhos de autorização, prompts, arquivos ou saídas aparecem nos rastreamentos	Bloqueie campos de segredos, minimize o registro de payloads, tokenize identificadores e teste a remoção de dados sensíveis
Operações humanas	Chaves são coladas em tickets, chats, procedimentos operacionais ou ferramentas de suporte	Use fluxos de acesso controlados, obtenção auditada de segredos, procedimentos de acesso emergencial e expiração automática

Esse mapa de fronteiras muda a pergunta de arquitetura de “Onde armazenamos a chave?” para “Qual identidade pode fazer qual requisição, com quais dados, por qual rota e que evidências ficam depois?”

Use um modelo de custódia de chaves no servidor

Credenciais de longa duração de provedores não devem ser entregues a clientes de navegador, aplicativos móveis, aplicativos desktop ou extensões. Considere que tudo o que é distribuído para o dispositivo de um usuário final pode ser extraído por ele ou por malware executado com os mesmos privilégios.

Um padrão mais seguro é:

1. O cliente se autentica no seu backend usando uma sessão de usuário, uma credencial de dispositivo ou um token de aplicação de curta duração.
2. Seu backend autoriza a funcionalidade solicitada e aplica limites por usuário ou tenant.
3. Um gateway ou uma integração no servidor escolhe o provedor e o modelo aprovados.
4. A chave do provedor é obtida em tempo de execução ou disponibilizada à carga de trabalho confiável pela plataforma de deployment.
5. A resposta do provedor retorna pela mesma fronteira de aplicação de políticas.

O cliente nunca precisa do segredo do provedor. Ele recebe apenas a autorização para chamar seu produto dentro dos limites que você define.

Para agentes de programação e ferramentas locais de desenvolvimento, use o mesmo princípio com um modelo de exceções definido de forma consciente. Um desenvolvedor pode precisar de uma credencial local, mas ela deve ser uma credencial do produto ou do gateway, com revogação, atribuição de uso e escopo limitado — não uma chave de provedor compartilhada por toda a organização e copiada para arquivos de configuração por toda a empresa.

Monte um inventário de chaves antes de fazer qualquer rotação

Projetos de rotação falham quando as equipes não sabem qual carga de trabalho usa cada chave. Crie um inventário legível por máquina e atribua um responsável antes de alterar as credenciais.

Registre, no mínimo:

Campo	Exemplo	Por que é importante
ID do segredo	prod-support-chat-anthropic-01	Uma referência interna estável que não é o valor do segredo
Provedor e projeto	Conta do provedor + identificador do projeto	Define a abrangência do impacto externo
Ambiente	Desenvolvimento, homologação, produção	Impede que sistemas de teste herdem permissões de produção
Carga de trabalho	support-chat-api	Permite atribuir o uso e revogar de forma direcionada
Responsável	Equipe e escala de plantão	Define a responsabilidade durante incidentes
Local de armazenamento	Caminho no gerenciador de segredos ou vínculo com o deployment	Mostra onde está a fonte oficial do segredo
Modelos/rotas permitidos	Família de modelos aprovada ou política do gateway	Limita usos inesperados
Limites de gastos e requisições	Orçamento da carga de trabalho, RPM, TPM ou controles de concorrência	Limita abusos e automações fora de controle
Criação e última rotação	Datas e horários	Torna visíveis as credenciais desatualizadas
Método de rotação	Duas chaves, alias de versão ou janela de manutenção	Evita mudanças improvisadas
Dependência para revogação	Serviços que precisam ser atualizados primeiro	Preserva a disponibilidade
Classificação dos dados	Públicos, internos, confidenciais, regulados	Conecta a política de chaves à governança de prompts

Não coloque o valor da chave no inventário. Armazene apenas metadados e uma referência ao segredo gerenciado.

Separe as identidades por ambiente, carga de trabalho e risco

O antipadrão mais comum é uma única chave de produção compartilhada por todos os serviços. Isso é conveniente até que um repositório, executor de testes, notebook de prestador de serviço ou transcrição de suporte a exponha. Nesse momento, a equipe não consegue revogar a chave sem interromper produtos sem relação com o vazamento.

Prefira identidades separadas para:

• Produção, homologação, desenvolvimento e testes locais.
• Tráfego de clientes, ferramentas internas, tarefas em lote e pipelines de avaliação.
• Fluxos de alto risco que podem chamar ferramentas ou processar dados confidenciais.
• Diferentes unidades de negócio ou tenants quando os limites contratuais exigirem separação.
• Acesso emergencial, que deve permanecer desativado ou sob controle rigoroso durante a operação normal.

Quando o provedor oferecer restrições, aplique-as. Elas podem incluir APIs, modelos, redes de origem, projetos, referenciadores, aplicações ou cotas permitidos. As orientações do Google Cloud para chaves de API, por exemplo, recomendam restringir as chaves, isolá-las, excluir as desnecessárias, evitar incluí-las em commits de repositórios e monitorar seu uso.

Se o provedor não oferecer controles suficientemente granulares, aplique-os no seu próprio gateway. Um gateway central pode validar a carga de trabalho que faz a chamada, associá-la a uma rota aprovada, aplicar orçamentos e limites de requisições e manter as credenciais dos fornecedores atrás de uma única fronteira no servidor, submetida a revisão. Consulte o guia de arquitetura de gateways de API de IA para uma visão mais ampla do projeto de roteamento e failover.

Trate a governança de prompts e logs como parte da gestão de chaves

Uma chave de API autoriza um caminho de dados. Proteger a chave sem controlar esse caminho deixa sem solução o principal risco específico da IA.

Antes de rotear uma requisição, classifique o payload e aplique a regra do mínimo necessário:

• Remova credenciais, tokens, cookies, chaves privadas e strings de conexão.
• Exclua os campos de que o modelo não precisa.
• Tokenize ou pseudonimize identificadores diretos quando a tarefa puder funcionar sem eles.
• Rejeite dados regulados sem suporte ou com restrições contratuais.
• Separe as instruções de sistema do conteúdo não confiável de usuários ou de fontes recuperadas.
• Valide os argumentos das ferramentas antes que um agente possa chamar sistemas externos.

Os logs precisam de um esquema explícito. Não dependa de os desenvolvedores se lembrarem de não registrar um objeto de requisição. Defina quais campos são permitidos e descarte ou transforme todo o restante.

Um evento útil em produção pode conter:

{
  "request_id": "req_01J...",
  "tenant_id_hash": "tnt_7f2...",
  "workload": "support-chat-api",
  "route_policy": "support-low-risk-v3",
  "provider": "selected-provider",
  "model": "selected-model",
  "input_tokens": 842,
  "output_tokens": 211,
  "latency_ms": 1370,
  "status": 200,
  "key_version": "v12",
  "redaction_policy": "customer-support-v4"
}

Por padrão, ele não deve conter o cabeçalho de autorização, a chave do provedor em texto puro, o prompt completo, o documento enviado, argumentos de ferramentas sem remoção de dados sensíveis ou a saída completa do modelo. Se for necessário capturar o payload para uma avaliação ou um incidente sob controle rigoroso, limite essa captura no tempo, controle o acesso e mantenha-a claramente separada da telemetria de rotina.

A folha de referência da OWASP sobre logs oferece uma base útil para excluir tokens de acesso, senhas, chaves de criptografia e outros dados sensíveis dos logs da aplicação.

Projete a rotação de chaves de API sem indisponibilidade

A rotação só funciona como controle se puder ser executada com segurança. Um procedimento que causa indisponibilidade será adiado até surgir uma emergência.

Use uma sequência com duas chaves ou segredos versionados quando o provedor permitir credenciais válidas simultaneamente:

1. Crie uma nova chave no provedor. Aplique as mesmas restrições da chave antiga ou restrições mais rigorosas.
2. Armazene-a como uma nova versão do segredo. Não sobrescreva o valor antigo se a plataforma oferecer versões ou aliases.
3. Implante os componentes que leem a nova versão. Atualize o gateway ou as cargas de trabalho para resolver o alias ou a versão atual.
4. Migre o tráfego e observe. Confirme as requisições bem-sucedidas, os modelos esperados, os gastos, os limites de requisições e as taxas de erro com a nova versão da chave.
5. Elimine os consumidores da chave antiga. Verifique os inventários de deployments, tarefas, workers e ambientes de recuperação de desastres.
6. Revogue a chave antiga. Não basta parar de usá-la; invalide-a no provedor.
7. Verifique a rejeição. Um teste controlado deve confirmar que a credencial antiga não funciona mais.
8. Registre as evidências. Salve datas e horários, responsáveis, cargas de trabalho afetadas, resultados da validação e a próxima data de revisão.

Em um sistema que permite selecionar a versão da chave, a aplicação deve fazer referência a um alias estável, em vez de fixar uma versão do segredo no código:

type ProviderCredential = {
  value: string;
  version: string;
};

async function loadProviderCredential(): Promise<ProviderCredential> {
  const activeVersion = await secretStore.resolveAlias("ai/provider/active");
  const value = await secretStore.readVersion("ai/provider", activeVersion);

  return { value, version: activeVersion };
}

Não imprima value, não serialize o objeto retornado nem o anexe a um erro. Registre nos logs apenas o identificador da versão, que não é secreto.

A folha de referência da OWASP sobre gestão de segredos recomenda planejar todo o ciclo de vida do segredo, incluindo criação, rotação, revogação, expiração, auditoria, backup e acesso emergencial. Ela também enfatiza a automação da rotação quando viável.

Impeça que segredos entrem em repositórios e logs de CI

Gerenciadores de segredos não resolvem o problema depois que uma credencial é copiada para o código-fonte, uma fixture, um artefato de build ou um registro de execução de CI.

Use controles em três etapas:

Antes do commit

• Forneça arquivos .env.example com placeholders, nunca com credenciais válidas.
• Mantenha arquivos locais de segredos fora do controle de versão.
• Execute um detector rápido de segredos em hooks de pré-commit para identificar padrões comuns de provedores e valores de alta entropia.
• Ensine aos desenvolvedores que excluir um segredo em um commit posterior não o remove do histórico.

No push e no pull request

• Ative a detecção de segredos no repositório e a proteção de push quando disponíveis.
• Adicione padrões personalizados para tokens internos de gateway que os detectores públicos não reconhecerão.
• Exija uma justificativa documentada para ignorar o bloqueio e encaminhe essas exceções para revisão de segurança.
• Verifique arquivos gerados, notebooks, snapshots de testes e planos de infraestrutura — não apenas o código-fonte da aplicação.

O GitHub documenta a proteção de push como uma forma de verificar o conteúdo durante o push e bloquear os segredos detectados antes que entrem em um repositório. A detecção não é motivo para manter a chave: trate qualquer credencial cuja inclusão em um commit tenha sido confirmada como exposta e faça a rotação.

Durante o CI/CD

• Prefira identidade de carga de trabalho ou federação de curta duração a credenciais de nuvem armazenadas.
• Disponibilize um segredo apenas para a tarefa e a etapa que precisam dele.
• Mascare os valores conhecidos de segredos, mas não dependa do mascaramento como controle principal.
• Desative o rastreamento de comandos do shell durante a obtenção de segredos.
• Impeça que código não confiável de forks acesse segredos de deployment.
• Revise artefatos, caches, dumps de falha e relatórios de testes para identificar capturas acidentais.

Monitore o uso sem registrar o segredo

Um bom monitoramento responde “quem usou qual permissão?” sem registrar a própria credencial que concede essa permissão.

Acompanhe:

• Carga de trabalho, ambiente, tenant ou projeto e versão da chave.
• Provedor, modelo, política de rotas e caminho de fallback.
• Contagem de requisições, volume de tokens, gastos, latência e categoria do erro.
• Rede de origem ou identidade do deployment, quando útil.
• Acessos ao gerenciador de segredos, incluindo leituras negadas.
• Criação de chaves, alterações de restrições, rotação, revogação e exclusão.
• Uso repentino em um ambiente, localização geográfica, modelo ou período inesperado.

Configure alertas com base no comportamento, não apenas no gasto total. Uma chave roubada com orçamento baixo ainda pode expor prompts ou sondar fluxos internos. Por outro lado, uma tarefa legítima em lote pode gerar um pico de gastos sem comprometimento de credenciais. Correlacione o uso do provedor com IDs de requisição da aplicação, decisões de política do gateway, eventos de deployment e logs de auditoria do gerenciador de segredos.

Para controles de tráfego que complementam os controles de credenciais, use o guia de limites de requisições de LLMs e o manual de roteamento de fallback para APIs de LLMs.

Meça o tempo entre a exposição e a revogação em incidentes

Quando uma chave pode ter sido exposta, o primeiro objetivo é conter o incidente — não provar se um invasor a usou.

Siga esta sequência:

1. Declare a credencial como suspeita. Registre quando e onde ela pode ter sido exposta.
2. Crie uma substituta pelo fluxo normal e controlado. Não cole uma chave nova no chat para agilizar a resposta ao incidente.
3. Migre as cargas de trabalho legítimas para a substituta. Use o procedimento de rotação preparado.
4. Revogue a chave suspeita. Se a revogação imediata causar um impacto inaceitável, isole as rotas e reduza os limites enquanto conclui a migração.
5. Busque em todos os locais que possam conter cópias. Verifique o histórico do código-fonte, logs de CI, artefatos, camadas de contêineres, sistemas de suporte, painéis, notebooks, configurações locais e backups.
6. Revise os caminhos de dados autorizados. Determine quais prompts, saídas, arquivos, ferramentas ou modelos a chave poderia acessar — não apenas seu escopo de cobrança.
7. Correlacione as atividades. Compare o uso do provedor, logs do gateway, deployments, leituras de segredos e atividades dos usuários.
8. Notifique os responsáveis adequados. Envolva as equipes de segurança, plataforma, jurídico, privacidade e atendimento ao cliente conforme os dados e contratos envolvidos.
9. Elimine a causa raiz. Adicione o detector, a restrição, a fronteira de identidade ou o filtro de logs que faltava.
10. Meça os tempos. Registre o tempo até a detecção, a substituição, a migração do tráfego, a revogação e a verificação.

A métrica mais útil para orientar ações costuma ser o tempo entre a exposição e a revogação: por quanto tempo uma credencial suspeita continua utilizável depois que a organização tem evidências confiáveis de exposição. Reduzir esse intervalo exige responsáveis definidos, inventário, automação e rotação testada — não um documento de políticas mais longo.

Se você emite chaves de API para seus próprios clientes

Muitos produtos de IA também distribuem chaves, por exemplo, para permitir que clientes chamem seu agente ou incorporem sua funcionalidade. As mesmas boas práticas se aplicam no sentido inverso:

• Gere chaves com um gerador de números aleatórios criptograficamente seguro, com pelo menos 32 bytes de entropia.
• Adicione um prefixo reconhecível (como sk-fk- nas chaves da Flatkey) para que detectores de segredos e sua equipe de suporte possam identificar chaves vazadas. O programa de parceiros do GitHub usa formatos de tokens conhecidos para notificar os emissores quando uma chave é enviada para um repositório público (detecção de segredos do GitHub).
• Mostre a chave completa uma única vez e depois armazene apenas um hash. Se o banco de dados vazar, as chaves permanecem seguras.
• Exiba apenas um prefixo mascarado no painel, junto com a data de criação e a data e hora do último uso.
• Torne a revogação imediata e retorne 401 para chaves revogadas.
• Permita que os clientes definam o escopo das chaves para modelos, projetos ou limites de gastos específicos.

Python: gere, calcule o hash e verifique chaves

import hashlib
import hmac
import secrets

PREFIX = "sk-acme-"

def new_api_key() -> tuple[str, str]:
    """Return (plaintext key shown to the user once, hash to store)."""
    key = PREFIX + secrets.token_urlsafe(32)  # 32 random bytes
    return key, hashlib.sha256(key.encode()).hexdigest()

def verify(presented: str, stored_hash: str) -> bool:
    candidate = hashlib.sha256(presented.encode()).hexdigest()
    return hmac.compare_digest(candidate, stored_hash)  # constant-time compare

key, digest = new_api_key()
print(key[:12] + "...")   # show the full key once in the UI, never log it
print(verify(key, digest))  # True

Um hash rápido como SHA-256 é aceitável aqui porque a chave é longa e aleatória, ao contrário de uma senha criada por uma pessoa. Armazene o hash, um ID da chave, o responsável, o escopo e as datas e horários.

Node.js: carregue uma chave do ambiente e bloqueie a operação em caso de falha

// Never fall back to a hardcoded default key.
const apiKey = process.env.FLATKEY_API_KEY;
if (!apiKey || !apiKey.startsWith("sk-fk-")) {
  throw new Error("FLATKEY_API_KEY is missing or malformed");
}

const res = await fetch("https://router.flatkey.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-haiku-5-5",
    messages: [{ role: "user", content: "ping" }],
    max_tokens: 5,
  }),
});
console.log(res.status); // log the status, never the header

Verifique se uma chave revogada realmente deixou de funcionar

A revogação só é comprovada quando a chave antiga falha. Após cada rotação ou incidente, execute uma verificação como esta em uma máquina confiável:

# Expect 401 for the revoked key; do not echo the key itself
OLD_KEY="$(cat /run/secrets/old_flatkey_key)"
status=$(curl -s -o /dev/null -w "%{http_code}" \
  https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $OLD_KEY")
if [ "$status" = "401" ]; then echo "revoked OK"; else echo "STILL ACTIVE: $status"; fi

Registre o resultado e o horário no seu registro de rotação. A Flatkey documenta que a revogação é imediata e que qualquer requisição com uma chave revogada recebe 401 Unauthorized, sem período de carência (documentação de chaves de API da Flatkey).

Como a Flatkey apoia essas boas práticas

A Flatkey oferece um único endpoint compatível com a OpenAI (https://router.flatkey.ai/v1) para vários provedores de modelos, o que significa menos chaves de provedores espalhadas pelos seus serviços. Segundo a documentação de chaves de API da Flatkey (consultada em 27 de outubro de 2026):

• Você pode criar várias chaves: uma por ambiente, aplicação ou membro da equipe, com nomes descritivos como prod-customer-chatbot.
• A chave sk-fk- completa é exibida apenas uma vez. Depois disso, a página Keys lista o nome, a data de criação, a data e hora do último uso e um prefixo mascarado.
• A revogação é imediata, então coloque a chave substituta em uso antes de revogar a antiga.
• Todas as chaves compartilham o saldo da conta e podem acessar todos os modelos por padrão. Use Groups no console para restringir uma chave a modelos específicos ou definir uma cota de gastos.

A documentação de uso descreve logs por requisição com modelo, tokens, custo e chave, além de um limite mensal de gastos e alertas de saldo baixo por e-mail, que atendem às práticas 10 e 11. Para organizações maiores, a documentação empresarial da Flatkey descreve subchaves organizadas em árvore, com orçamentos próprios e listas de modelos permitidos. Um gateway não substitui a autenticação dos seus clientes, a classificação dos dados e os cuidados com os logs; por isso, mantenha o restante deste checklist em vigor. Para começar, consulte o guia inicial de integração da Flatkey.

Arquitetura de referência para produtos de IA com vários provedores

Uma configuração segura com vários provedores pode ser organizada em cinco camadas:

1. Camada de identidade do cliente: autentica o usuário, dispositivo, agente ou aplicação sem expor credenciais dos provedores.
2. Camada de autorização da aplicação: verifica os direitos de uso do produto, os limites entre tenants, o acesso a funcionalidades e os orçamentos.
3. Camada de políticas de dados: classifica e remove dados sensíveis de prompts, arquivos, contexto recuperado e argumentos de ferramentas.
4. Camada de gateway e roteamento: seleciona modelos aprovados, aplica cotas, registra a atribuição de uso sem segredos e gerencia o failover.
5. Camada de credenciais dos provedores: armazena credenciais isoladas dos fornecedores, faz a rotação das versões e as disponibiliza apenas à carga de trabalho confiável de roteamento.

Esse projeto limita a abrangência do impacto. Um token de cliente comprometido não revela automaticamente uma chave de provedor. Uma identidade de carga de trabalho comprometida não deve conceder acesso a todos os provedores. Uma credencial de provedor vazada não deve autorizar todos os ambientes. Uma falha de logs não deve expor tanto o segredo quanto o payload completo.

Checklist de produção

Use este checklist antes do lançamento e durante as revisões trimestrais dos controles.

Custódia e identidade

• [ ] Nenhuma chave de longa duração de provedor é distribuída no código de navegador, aplicativo móvel, aplicativo desktop ou extensão.
• [ ] Toda carga de trabalho de produção tem um responsável identificável e um caminho definido de obtenção de credenciais.
• [ ] Os acessos de produção, homologação, desenvolvimento, avaliação e uso local estão separados.
• [ ] Chaves compartilhadas entre pessoas foram substituídas por identidades de carga de trabalho ou de gateway sempre que possível.
• [ ] As restrições do provedor e do gateway estão configuradas com o escopo mais restrito viável.

Armazenamento e entrega

• [ ] A fonte oficial dos segredos é um repositório gerenciado ou um vínculo controlado com o deployment.
• [ ] As aplicações obtêm segredos apenas em tempo de execução e não os imprimem nem serializam.
• [ ] As tarefas de CI recebem apenas os segredos necessários para a etapa exigida.
• [ ] O acesso a segredos e as alterações administrativas são auditados.
• [ ] O acesso emergencial está documentado, tem duração limitada e foi testado.

Dados e observabilidade

• [ ] Cabeçalhos de autorização e valores de chaves são excluídos de logs, rastreamentos, erros e exportações de suporte.
• [ ] O registro de prompts, saídas, arquivos e argumentos de ferramentas segue um esquema de campos permitidos.
• [ ] A remoção de dados sensíveis acontece antes do roteamento entre vários provedores.
• [ ] O uso pode ser atribuído à carga de trabalho, ao ambiente, à rota, ao provedor, ao modelo e à versão da chave.
• [ ] Os alertas abrangem rotas e identidades incomuns, além dos gastos.

Rotação e resposta

• [ ] Existe um procedimento testado de rotação com duas chaves ou segredos versionados.
• [ ] As chaves antigas são revogadas no provedor e verificadas para confirmar que não podem mais ser usadas.
• [ ] A detecção de segredos e a proteção de push abrangem repositórios e artefatos gerados.
• [ ] Uma suspeita de vazamento aciona a contenção imediata, sem esperar por provas de abuso.
• [ ] O tempo entre a exposição e a revogação é medido após simulações e incidentes.

Perguntas frequentes

Quais são as boas práticas de gestão de chaves de API?

Mantenha as chaves fora do código-fonte e dos aplicativos cliente, use uma chave separada por ambiente e carga de trabalho, restrinja cada chave às APIs, aos modelos e ao orçamento de que precisa, armazene as chaves em um gerenciador de segredos, faça a rotação em um cronograma testado, exclua chaves sem uso, ative a detecção de segredos, nunca registre chaves nos logs e revogue imediatamente quando houver suspeita de vazamento.

Uma chave de API deve ser armazenada em uma variável de ambiente?

Variáveis de ambiente são uma forma razoável de entregar uma chave a um processo, mas não são um sistema de gestão. O valor deve vir de um gerenciador de segredos ou da injeção de segredos da sua plataforma, com controle de acesso, rotação e auditoria. Nunca inclua arquivos .env em commits.

Com que frequência as chaves de API devem passar por rotação?

Escolha um intervalo com base no risco e nos controles do provedor; muitas equipes fazem a rotação das chaves de IA de produção a cada 90 dias e imediatamente após mudanças na equipe ou suspeita de exposição. O mais importante é que a rotação seja ensaiada, a chave antiga seja revogada e a revogação seja verificada.

Um navegador ou aplicativo móvel pode chamar um provedor de IA diretamente com uma chave de API?

Evite isso. Tudo o que é distribuído para um dispositivo pode ser extraído. Faça o cliente se autenticar no seu backend e deixe que o backend ou gateway chame o modelo com uma chave no servidor e limites por usuário.

O que devo fazer se uma chave de API vazar no GitHub?

Trate-a como comprometida. Crie uma substituta, migre as cargas de trabalho para ela, revogue a chave vazada, confirme que ela retorna 401, revise o uso durante o período de exposição e adicione detecção de segredos ou proteção de push para evitar que isso se repita. Excluir o commit não torna a chave segura.

Uma única chave de gateway é mais segura do que várias chaves de provedores?

Ela reduz o número de segredos no código, mas concentra as permissões. Use chaves de gateway separadas por ambiente e carga de trabalho, defina o escopo com limites de modelos e gastos e proteja as chaves dos provedores atrás do gateway com o mesmo cuidado de antes.

Como devo armazenar as chaves de API que emito para meus próprios usuários?

Armazene apenas um hash de cada chave, mostre a chave completa uma única vez na criação, exiba um prefixo mascarado depois disso e ofereça revogação imediata.

Fontes e leituras complementares

• Folha de referência da OWASP sobre gestão de segredos
• Folha de referência da OWASP sobre logs
• GitHub: sobre a detecção de segredos
• GitHub: sobre a proteção de push
• Google Cloud: boas práticas de gestão de chaves de API
• Flatkey: crie e gerencie chaves de API

Guias relacionados da Flatkey: política de remoção de dados sensíveis em APIs de IA, arquitetura de gateways de API de IA e limites de requisições de LLMs explicados.