Chaves de API

O problema: sistemas não digitam senha

O tópico de autenticação trata de pessoas: um login, uma sessão, um token que expira em minutos. Mas boa parte do tráfego de uma API vem de outros sistemas: o ERP do parceiro que consulta pedidos de madrugada, o script de integração, o servidor de outra empresa. Eles não fazem login nem respondem a um segundo fator.

A solução mais comum é a chave de API: um segredo longo, gerado pelo seu sistema, que o cliente envia a cada pedido.

GET /pedidos HTTP/1.1
Host: api.loja.exemplo.com
Authorization: Bearer loja_live_jDosv23if64z0lM97juGvKwxStdHurfvUoRmL6EiuqI

É simples, e funciona com qualquer linguagem, ferramenta e curl. Os problemas aparecem no ciclo de vida: como a chave é gerada, guardada, limitada, trocada e, principalmente, o que acontece quando ela vaza.

Gerar: aleatória e longa

A chave do exemplo tem um prefixo e 32 bytes aleatórios, 256 bits, codificados em base64url. Com 256 bits, adivinhar uma chave válida está fora de alcance, mesmo com milhões de chaves cadastradas. A geração precisa usar o gerador criptográfico da linguagem (crypto.randomBytes, secrets, crypto/rand, SecureRandom, RandomNumberGenerator), e não um Math.random ou um UUID versão 1, que é previsível.

Guardar: só o hash, e um hash rápido

Se a tabela de chaves vazar num backup ou numa invasão, todas as integrações ficam expostas. Por isso, como as senhas, a chave é guardada só como hash: o servidor calcula o hash da chave recebida e procura esse hash na tabela. A chave em si aparece para o cliente uma única vez, na criação.

A diferença para as senhas está no algoritmo. Senhas são curtas e previsíveis, e precisam de um hash lento, como mostra o tópico de hash de senhas. Uma chave de 256 bits aleatórios não pode ser adivinhada com dicionário nenhum, então um hash rápido basta, e o custo de um lento aparece em cada pedido. Medimos num núcleo:

Com bcrypt, cada pedido autenticado gastaria 66 ms de CPU, e um núcleo atenderia 15 pedidos por segundo. Com SHA-256, a verificação é desprezível. E o SHA-256 ainda permite buscar a chave por um índice único no banco, porque o mesmo valor sempre gera o mesmo hash. O bcrypt usa um sal aleatório e obrigaria a comparar a chave recebida com cada linha da tabela.

Enviar: no cabeçalho, nunca na URL

Algumas APIs aceitam a chave na URL: /pedidos?api_key=.... É prático para testar no navegador, e é um vazamento garantido. A URL aparece em logs de proxies, de balanceadores, de ferramentas de monitoramento e no histórico do navegador.

Testamos com um Nginx na configuração padrão de logs, com um pedido de cada forma:

"GET /pedidos?api_key=loja_live_SEGREDO_NA_URL HTTP/1.1" 200 3 "-" "curl/8.5.0"
"GET /pedidos HTTP/1.1" 200 3 "-" "curl/8.5.0"

A chave na URL foi parar no log. A do cabeçalho Authorization, não. Os exemplos da Implementação recusam a chave na URL, mesmo válida.

Quando vaza: o prefixo ajuda a encontrar

Chaves vazam: num commit esquecido, num print enviado ao suporte, num log copiado para um chamado. Quanto antes o vazamento for encontrado, menor o estrago. Ferramentas de varredura de segredos (secret scanning), como o gitleaks e a varredura do GitHub, procuram segredos em repositórios. Para encontrar uma chave, elas precisam reconhecer o formato.

Testamos o gitleaks (versão 8.30) com uma frase comum num chamado de suporte, contendo duas chaves: uma com o prefixo loja_live_ e outra sem prefixo, ambas aleatórias.

As regras padrão só encontraram as duas quando estavam atribuídas a uma variável com nome sugestivo (LOJA_KEY=...) ou num comando curl com o cabeçalho Authorization. No meio de um texto, uma chave sem prefixo é só uma sequência aleatória de caracteres, indistinguível de qualquer outra. Com um prefixo próprio, uma regra simples a encontra em qualquer lugar. É por isso que provedores como Stripe (sk_live_), GitHub (ghp_) e Slack (xoxb-) usam prefixos.

O teste achou também um erro na nossa primeira regra. Com loja_(live|test)_, o gitleaks registrou como segredo só o trecho live, porque usa o primeiro grupo da expressão como o valor do segredo. A regra correta usa um grupo que não captura: (?:live|test).

Limitar o estrago

Uma chave vazada vale até ser revogada. Três decisões limitam o que ela permite:

E o registro de uso (quando e de onde cada chave foi usada pela última vez) mostra se uma chave vazada chegou a ser usada, e quais chaves estão abandonadas e podem ser removidas.

Por que isso importa quando a IA escreve o código

Um assistente que implementa "autenticação por chave de API" costuma acertar o fluxo e errar o ciclo de vida:

• A chave guardada em texto puro na tabela, ou criptografada de forma reversível.
• bcrypt na verificação, deixando cada pedido 60 ms mais lento, ou um hash rápido sem índice único.
• Math.random, um UUID ou um carimbo de tempo como chave.
• A chave aceita na URL, e registrada nos logs.
• Uma chave por cliente, sem escopo nem validade, que não pode ser trocada sem derrubar a integração.
• Nenhum prefixo, e nenhum registro de último uso.

O próximo nível compara a chave de API com as alternativas e mostra como fazer a rotação sem derrubar quem integra.