Para proteger uma chave de API de LLM, guarde-a num gerenciador de segredos e chame o modelo só a partir do seu servidor, nunca de um navegador ou app. Dê a cada carga de trabalho sua própria chave, faça rotação das chaves periodicamente, prenda-as aos IPs dos seus servidores com uma lista de IPs permitidos e, se uma chave vazar, revogue primeiro e investigue depois.
Este post cobre os hábitos que mantêm as chaves seguras, com os controles específicos que a BroadNet Inference oferece. Para o passo a passo no portal, veja o guia de chaves de API e listas de IPs permitidos; para orçamentos e proteção contra loops descontrolados, veja controle de gastos com APIs de LLM.
Onde guardar uma chave de API de LLM?
Guarde as chaves num gerenciador de segredos ou nos segredos criptografados da sua plataforma, nunca no código. O OWASP Secrets Management Cheat Sheet cobre as opções em detalhe. Repare no alerta dele: variáveis de ambiente “are generally accessible to all processes and may be included in logs or system dumps” (tradução: em geral ficam acessíveis a todos os processos e podem acabar em logs ou dumps do sistema), por isso a OWASP prefere, quando você pode escolher, arquivos de segredo montados ou buscar os segredos num cofre. Uma variável de ambiente preenchida por um gerenciador de segredos na inicialização é o meio-termo mais comum.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"], # fails loudly if missing
)
Use os.environ[...], não os.getenv(...) com um valor padrão fixo no código; é justamente assim que chaves vão parar no Git. No desenvolvimento local, um arquivo .env serve, desde que esteja no .gitignore desde o primeiro commit. Ative o secret scanning e a push protection do seu host Git. No GitHub, a push protection bloqueia pushes que contêm formatos de segredo conhecidos antes que cheguem ao repositório; a push protection para usuários vem ativada por padrão, mas a do nível do repositório vem desativada por padrão e precisa ser ativada por um administrador do repositório ou por um owner da organização.
Dá para colocar uma chave de API num navegador ou app mobile?
Não. Tudo o que vai para um cliente pode ser extraído. Código de front-end e bundles de app são públicos, por mais minificados ou ofuscados que estejam. Chame o LLM do seu servidor, autentique seus próprios usuários ali e aplique seus próprios limites por usuário antes de repassar a requisição.
O mesmo vale para ferramentas desktop que você entrega a outras pessoas. Se um colega precisa de acesso a um agente de código, dê a ele uma chave própria na conta dele, em vez de compartilhar uma.
Por que dar a cada carga de trabalho sua própria chave?
Na BroadNet Inference, uma conta pode ter até dez chaves ativas. Use-as:
| Rótulo da chave | Usada por |
|---|---|
prod-api |
Backend de produção |
prod-worker |
Jobs em lote |
staging |
Ambiente de staging |
agent-ci |
Agente de código na CI |
dev-laptop-<name> |
Desenvolvimento local |
Quando uma vaza, você revoga só aquela, e as outras continuam funcionando. Os rótulos também deixam o uso legível: dá para ver qual carga de trabalho gasta quanto. Dê às chaves o nome do que as usa, não de quem as criou.
Como as listas de IPs permitidos protegem uma chave?
Com uma lista de IPs permitidos, uma chave roubada não funciona em lugar nenhum fora da sua infraestrutura. Na BroadNet Inference:
- A lista da conta aceita até 32 entradas, um endereço IPv4 ou IPv6 ou um intervalo CIDR por linha.
- Uma lista vazia significa sem restrição.
- Chaves novas herdam a lista da conta, a menos que você crie uma chave com seus próprios
allowed_ips, que substituem a lista herdada para aquela chave. - Uma requisição de um endereço fora da lista é recusada com 403 (“refused by model, route or IP policy”; tradução: recusada pela política de modelo, rota ou IP).
Crie uma chave com lista própria pela API do portal:
curl -X POST https://inference.broadnet.ai/portal/keys \
-H "Authorization: Bearer $BROADNET_PORTAL_CREDENTIAL" \
-H "Content-Type: application/json" \
-d '{"label":"prod-worker","allowed_ips":["203.0.113.7","198.51.100.0/24"]}'
A resposta traz a chave original uma única vez. Guarde-a imediatamente no seu gerenciador de segredos; ela não pode ser lida de novo. O passo a passo completo está no guia de listas de IPs permitidos.
Listas de IPs permitidos servem para servidores com IPs de saída estáveis: uma VPS, um NAT gateway, um IP fixo de escritório. Para notebooks que mudam de rede, use uma chave separada sem lista e mantenha pequena a exposição do saldo.
Por que separar chaves de inferência das credenciais de administração?
A BroadNet usa dois tipos de credencial:
| Credencial | O que pode fazer | Onde guardar |
|---|---|---|
| Chave de inferência | Requisições a modelos em /v1/* |
Onde o app roda |
| Credencial do portal | Criar e revogar chaves, mudar IPs permitidos, fazer compras | Só nas suas ferramentas de automação ou administração |
A documentação diz para tratar cada credencial do portal como autoridade total sobre a conta. Nunca coloque uma credencial do portal junto da sua aplicação. Se o servidor do app for comprometido, o atacante deve conseguir uma chave de inferência, não o controle da conta.
Com que frequência fazer a rotação de chaves de API?
A OWASP recomenda rotação regular “so that any stolen credentials will only work for a short time” (tradução: para que credenciais roubadas funcionem só por pouco tempo). As chaves da BroadNet duram um ano a partir da criação, então toda chave vai precisar ser trocada de qualquer jeito. Faça da rotação uma rotina:
- Crie uma chave nova com o mesmo padrão de rótulo e a mesma lista de IPs permitidos.
- Coloque-a no ar ao lado da antiga, ou troque o segredo e reinicie.
- Acompanhe o tráfego migrar para a chave nova.
- Revogue a chave antiga com
DELETE /portal/keys/{alias}.
Como uma conta pode ter até dez chaves ativas, você pode manter a antiga e a nova juntas por alguns minutos, sem indisponibilidade. Antecipe a rotação das chaves às quais tinha acesso alguém que está saindo da equipe.
O que fazer quando uma chave vaza?
Quando uma chave vaza, revogue primeiro e investigue depois. Na BroadNet Inference, novas requisições param em até cinco segundos depois de uma revogação ou mudança na lista de IPs permitidos; a documentação explica que as decisões de autorização podem ficar num cache replicado durante esse intervalo limitado.
Depois de revogar:
- verifique o uso da chave na página da conta ou em
GET /portal/usage; - descubra como ela vazou (histórico de commits, logs de CI, uma captura de tela compartilhada);
- faça a rotação de outros segredos guardados no mesmo lugar.
Uma chave revogada ou bloqueada retorna 401 ou 403; veja o guia de erros para que seu monitoramento não trate esses códigos como transitórios.
Como as chaves vazam pelos logs?
Logs são um vazamento fácil de deixar passar. Mascare o cabeçalho Authorization no log de depuração HTTP, nas ferramentas de relatório de erros e nos logs de acesso de proxies. Ao falar com o suporte, envie o X-Request-ID, o horário, a rota, o status e o alias da chave, nunca a chave em si. A documentação da BroadNet diz que o portal guarda só um hash de cada chave, então ele também não consegue mostrar uma chave perdida.
Como limitar o estrago de um vazamento que você ainda não descobriu?
Mesmo com todos os hábitos acima, conte com a possibilidade de uma chave vazar um dia. Reduza o raio de impacto:
- Mantenha o saldo de pagamento por uso num nível que você aceitaria perder, e recarregue conforme precisar.
- Use um plano de preço fixo para agentes pesados: uma sessão de plano tem preço fixo, então uma chave de plano roubada não consegue inflar uma conta por token. Veja o que “ilimitado” realmente significa.
- Configure alertas para gasto ou taxa de requisições fora do normal por chave; a calculadora de custo de API de LLM dá um valor mensal normal para usar como referência nos alertas. Nosso post sobre controle de gastos com APIs de LLM cobre orçamentos e alertas.
Quais controles de chave a BroadNet Inference oferece?
| Controle | BroadNet Inference |
|---|---|
| Chave mostrada uma vez, guardada como hash | Sim |
| Chaves ativas por conta | Até 10 |
| Validade da chave | Um ano |
| Lista de IPs permitidos | Até 32 entradas IPv4, IPv6 ou CIDR |
| Lista de IPs permitidos por chave | Sim, allowed_ips na criação |
| A revogação passa a valer | Em até cinco segundos |
| Credencial de administração separada | Credencial do portal |
As chaves protegem sua conta; a retenção zero de dados protege o que você envia por ela. Leia sobre as duas antes de colocar em produção.
