Chaves de API
Autenticação entre sistemas, com geração, armazenamento, escopo e rotação das chaves.
As decisões sobre chaves de API são quatro: se a chave é a forma certa de autenticar, qual o formato, como guardá-la e como trocá-la sem derrubar a integração.
Chave de API ou outra forma
| Forma | Como funciona | Vantagens | Custos |
|---|---|---|---|
| Chave de API | Um segredo fixo enviado a cada pedido | Simples, funciona em qualquer ferramenta | Vale até ser revogada; vaza em logs e repositórios |
| OAuth2 com credenciais do cliente | O sistema troca um identificador e um segredo por um token que expira em minutos | O token vazado vence logo; escopos padronizados | Um servidor de autorização; mais uma ida e volta |
| Pedido assinado (HMAC, como a AWS faz) | O cliente assina cada pedido com o segredo, que nunca trafega | O segredo não aparece em logs; um pedido capturado não pode ser alterado | Implementação mais difícil para quem integra |
| TLS mútuo | O cliente apresenta um certificado na conexão | Forte, sem segredo no pedido | Emissão e renovação de certificados |
A chave de API é a escolha mais comum para APIs públicas e integrações simples, porque qualquer pessoa consegue usá-la em minutos. OAuth2 com credenciais do cliente compensa quando já existe um servidor de autorização e quando os parceiros conseguem lidar com tokens que expiram. O pedido assinado e o TLS mútuo aparecem em integrações financeiras e entre empresas com mais exigência de segurança.
O formato da chave
| Parte | Exemplo | Por quê |
|---|---|---|
| Prefixo do produto | loja_ | A varredura de segredos encontra a chave em qualquer texto |
| Ambiente | live_ ou test_ | Quem integra vê na hora se está usando a chave de produção |
| Parte aleatória | 32 bytes em base64url | Impossível de adivinhar |
| Dígito verificador (opcional) | Um CRC32 no fim | Ferramentas recusam chaves digitadas errado ou inventadas sem consultar o banco |
O prefixo também permite registrar a chave na varredura de segredos do GitHub como parceiro, para que um vazamento num repositório público seja avisado a você.
Para mostrar a chave na tela sem revelá-la, guarde também os últimos quatro caracteres: "loja_live_…uqI, criada em 3 de março, usada pela última vez há 2 horas".
Como guardar
| Opção | Busca | Se a tabela vazar | Custo por pedido |
|---|---|---|---|
| Texto puro | Índice | Todas as chaves expostas | Nenhum |
| Criptografada | Índice, se a cifra for determinística | Expostas se a chave de cifra vazar junto | Baixo |
| Hash lento (bcrypt, Argon2) | Sem índice: compara com cada linha, ou exige um identificador separado | Seguro | Alto: 66 ms por verificação no teste |
| Hash rápido (SHA-256) | Índice único | Seguro, porque a chave é aleatória e longa | Desprezível |
O SHA-256 com índice único é a escolha certa para chaves geradas pelo seu sistema. O hash lento só faz sentido para segredos que uma pessoa escolhe, como senhas.
Uma variação comum separa a chave em duas partes, um identificador público e um segredo: loja_live_<identificador>_<segredo>. O identificador localiza a linha e aparece nos logs sem risco. O segredo é conferido pelo hash. Assim, um log de acesso pode registrar qual chave foi usada sem guardar o segredo.
Como trocar sem derrubar a integração
Uma chave fixa para sempre é uma chave que um dia vaza e ninguém percebe. A troca periódica (rotação) limita esse tempo, mas precisa acontecer sem derrubar o sistema do cliente:
- O cliente cria uma segunda chave, com os mesmos escopos, enquanto a primeira continua valendo.
- Ele atualiza a configuração do sistema dele para usar a nova.
- O registro de uso mostra quando a chave antiga parou de ser usada.
- O cliente, ou uma expiração programada, revoga a chave antiga.
Isso exige que cada cliente possa ter várias chaves ativas ao mesmo tempo. Com uma chave só por cliente, a troca obriga a uma janela de indisponibilidade, e por isso nunca acontece.
Em caso de vazamento, o caminho é o mesmo, mas com pressa: revogar a chave vazada assim que a nova estiver em uso, ou na hora, se o vazamento for grave.
Limitar e observar
| Medida | Para quê |
|---|---|
| Escopos por chave | A chave de leitura não escreve |
| Validade | Chaves de teste e de parceiros temporários expiram sozinhas |
| Limite de requisições por chave | Uma chave vazada não esgota a API, como mostra o tópico de limite de requisições |
| Restrição por IP, quando o cliente tem IPs fixos | A chave vazada não funciona de fora da rede do cliente |
| Último uso, com data e IP | Detectar uso indevido e chaves abandonadas |
| Aviso de vazamento | Revogar ou avisar o cliente quando a varredura encontrar a chave |
Resumo da decisão
- Chave de API para integrações simples; OAuth2 com credenciais do cliente quando os parceiros conseguem lidar com tokens que expiram.
- Formato com prefixo e ambiente, e 256 bits aleatórios.
- SHA-256 com índice único, e a chave mostrada uma única vez.
- Várias chaves por cliente, cada uma com escopos e validade, para permitir a rotação.
- Só no cabeçalho, nunca na URL.
- Último uso registrado, limite de requisições por chave e uma regra na varredura de segredos.
O próximo nível mostra a autenticação por chave nas cinco linguagens, testada com chaves válidas, revogadas, expiradas, sem escopo e na URL.
Prompts para aprofundar
Ao abrir no ChatGPT ou no Claude, o prompt é enviado ao serviço escolhido pela URL e também fica copiado na sua área de transferência.
Desenhar as chaves de API do meu sistema
Quero oferecer chaves de API para os clientes do meu sistema. Pergunte quem vai integrar, o que as integrações precisam fazer, qual linguagem e banco eu uso e se já existe um servidor de autorização. Proponha, explicando o porquê: 1. Chave de API ou OAuth2 com credenciais do cliente. 2. O formato da chave, com prefixo e ambiente. 3. A tabela, com hash, escopos, validade e último uso. 4. A tela onde o cliente cria, vê e revoga as chaves. 5. A política de rotação e de remoção de chaves abandonadas.
Plano para uma chave vazada
Quero um plano para o dia em que uma chave de API de um cliente vazar. Pergunte como as chaves funcionam hoje no meu sistema e como os clientes são avisados de incidentes. Monte comigo: 1. Como o vazamento é detectado: varredura de segredos, avisos de parceiros, uso anormal. 2. Como avaliar se a chave foi usada indevidamente. 3. Quando revogar na hora e quando esperar a troca. 4. Como avisar o cliente e ajudá-lo a trocar a chave. 5. O que mudar para o mesmo vazamento não se repetir.
Rotação de chaves sem indisponibilidade
Quero que os clientes do meu sistema consigam trocar as chaves de API sem derrubar as integrações. Pergunte quantas chaves cada cliente pode ter hoje e como elas são usadas. Explique: 1. Por que a rotação exige várias chaves ativas por cliente. 2. O passo a passo da troca, do lado do cliente. 3. Como o registro de último uso mostra que a chave antiga parou de ser usada. 4. Expiração programada e lembretes antes do vencimento. 5. Como fazer o mesmo com os segredos que o meu sistema usa para chamar APIs de terceiros.