O que é uma chave de API? Como funciona e como protegê-la

A API de Scraping Scrapeleless autentica solicitações através do cabeçalho x-api-token, onde uma chave de API de conta Scrapeless identifica o cliente que faz a chamada.

O que é uma chave de API?

Uma chave de API é um valor que um provedor de API emite para um cliente de software, projeto, conta ou integração. O cliente inclui a chave em uma solicitação. O gateway de API ou aplicativo procura a credencial, verifica seu status e restrições, aplica a política e associa a solicitação a um proprietário para fins de acesso, uso e auditoria.

A palavra “chave” pode ser enganosa. Uma chave de API não é necessariamente uma chave criptográfica usada para criptografar ou assinar dados. Em muitos sistemas, é uma credencial aleatória opaca. Alguns designs usam um identificador público mais um componente secreto; outros codificam um prefixo reconhecível que ajuda os operadores a identificar o tipo de credencial sem revelar o segredo.

Chaves de API são comuns para APIs de servidor para servidor, ferramentas de desenvolvedor, serviços de dados, mapas, mensagens, automação e serviços internos. Seu apelo é a simplicidade operacional: o cliente envia uma credencial e o provedor pode atribuir a chamada. Essa simplicidade é segura apenas quando a chave é gerada com entropia suficiente, transmitida com segurança, armazenada como um segredo e restrita à menor autoridade útil.

Como funciona a autenticação de chave de API

1. O provedor emite uma credencial. Um painel ou API administrativa cria uma chave para um projeto nomeado, conta de serviço ou integração.
2. O cliente armazena o segredo. Aplicações de servidor leem isso de um gerenciador de segredos, injeção de ambiente protegida ou outro armazenamento de credenciais aprovado.
3. O cliente envia uma solicitação. A chave normalmente aparece em um cabeçalho HTTP sobre TLS.
4. O serviço resolve a chave. Um identificador de chave ou pesquisa segura encontra o registro de credencial armazenado sem expor segredos não relacionados.
5. O serviço avalia a política. Verifica status ativo, escopos, restrições de recursos, condições de rede, cotas e outros controles.
6. O serviço registra dados de auditoria seguros. Os logs usam um ID de chave ou impressão digital, não o segredo completo, para atribuir a operação.

Uma solicitação pode ser autenticada, mas não autorizada. A autenticação responde a qual cliente apresentou a credencial. A autorização responde se aquele cliente pode realizar esta ação neste recurso. Um serviço deve tomar ambas as decisões de forma explícita.

Onde uma chave de API deve ser enviada?

Um cabeçalho específico de API ou o cabeçalho padrão Authorization normalmente é o local correto. A API de Scraping Scrapeleless usa esta forma de cabeçalho:

x-api-token: REDACTED

A solicitação deve usar HTTPS para que o transporte proteja os cabeçalhos de observação de rede passiva e autentique o servidor. TLS não protege uma chave depois que ela chega aos logs da aplicação, rastreamentos de depuração, extensões de navegador ou pontos finais comprometidos, por isso os controles de armazenamento e observabilidade permanecem necessários.

O OWASP REST Security Cheat Sheet aconselha contra colocar chaves de API e outros tokens de segurança em URLs porque os URLs são capturados por muitos sistemas. A autenticação de string de consulta pode existir por compatibilidade, mas uma nova API deve preferir cabeçalhos.

O que uma chave de API pode e não pode provar

Uma chave válida prova que o chamador possui aquela credencial no momento da solicitação. Não prova qual humano iniciou a solicitação, se o dispositivo é confiável ou se o software que apresenta a chave é o software pretendido. Uma chave copiada pode muitas vezes ser reproduzida de outra máquina, a menos que o provedor adicione restrições ou prova ligada ao remetente.

Chaves incorporadas em páginas da web públicas, binários de desktop, extensões de navegador e aplicativos móveis não podem ser mantidas como segredos duráveis porque os usuários controlam esses ambientes. A ofuscação pode retardar a descoberta casual, mas não muda o modelo de confiança. Clientes públicos devem chamar um backend controlado ou usar um design de autorização criado para software público.

Uma chave de API também não deve substituir permissões de nível de usuário para recursos sensíveis. Se cada ação do usuário compartilhar uma única chave de projeto, o serviço não pode distinguir de forma confiável o consentimento individual, funções ou revogação. A autenticação e autorização de usuários pertencem a uma camada separada.

Chave de API vs OAuth vs Token Bearer

Essas categorias se sobrepõem. Um token de acesso OAuth é comumente usado como um token bearer. Uma chave de API também pode ser apresentada com um esquema bearer, embora essa apresentação não transforme o sistema em OAuth. Um JWT pode ser usado como um token bearer, mas tokens bearer opacos também são comuns.

Design da chave API

Uma chave bem projetada é gerada a partir de uma fonte aleatória criptograficamente segura e é longa o suficiente para resistir a adivinhações. O valor não deve codificar dados de conta sensíveis. Um prefixo reconhecível pode ajudar scanners secretos e operadores a identificar o provedor e o tipo de credencial, mas a parte imprevisível deve levar a segurança.

Muitos serviços mostram o segredo completo apenas uma vez. O backend armazena um verificador unidirecional ou uma representação secreta protegida em vez de manter cada credencial em texto plano disponível para exibição. Um ID de chave não secreto separado suporta pesquisa, registros e administração.

O sistema deve permitir várias chaves ativas por projeto para que as implantações possam mudar credenciais sem um segredo compartilhado em todos os ambientes. Cada chave precisa de um nome, proprietário, evento de criação, informações de último uso, restrições e controle de revogação.

Como Armazenar Chaves de API

Serviços de produção devem recuperar chaves de um sistema centralizado de gerenciamento de segredos ou de um armazenamento de segredos de plataforma aprovado. O acesso deve ser limitado à identidade de carga de trabalho que precisa do segredo. O acesso humano, exportações e mudanças administrativas devem ser auditáveis.

O Cheat Sheet de Gerenciamento de Segredos OWASP cobre armazenamento central, provisionamento, auditoria, rotação e controles de ciclo de vida. Variáveis de ambiente podem ser um mecanismo de entrega, mas não são automaticamente privadas: inspeção de processo, relatórios de falhas, registros de compilação ou diagnósticos descuidados podem expô-las.

Não comprometa chaves no controle de origem, coloque-as em imagens de contêiner, cole-as em rastreadores de problemas ou compartilhe-as através de chat. A entrada CWE-798 sobre credenciais codificadas explica por que credenciais incorporadas em software criam ampla exposição e são difíceis de mudar.

Escopo e Restrições

Uma chave deve conceder apenas as APIs, operações, recursos e ambientes que sua carga de trabalho necessita. Separe credenciais de desenvolvimento, homologação e produção. Use autoridade somente para leitura quando um processo nunca escreve. Limite quotas para que um vazamento não possa criar custo ou tráfego ilimitado.

Restrições de rede, origens permitidas, assinaturas de aplicação ou identidades de serviço podem adicionar contexto útil, mas cada controle tem limitações. Regras de IP fonte são difíceis para redes móveis e egressos compartilhados. Restrições de origem do navegador protegem apenas fluxos de navegador participantes e não tornam uma chave exposta secreta. Trate restrições como camadas, não como substitutos para proteção de credencial.

Rotação e Revogação

A rotação substitui uma credencial antiga por uma nova. Um processo seguro cria uma segunda chave, atualiza a carga de trabalho através do caminho de entrega do segredo, confirma o tráfego sob o novo ID de chave e, em seguida, revoga a chave antiga. O suporte a várias chaves evita uma implantação forçada simultânea em todas as instâncias.

Revogue uma chave imediatamente quando a exposição for suspeita, um proprietário deixar, uma integração ser descontinuada ou a credencial não tiver mais um propósito justificado. O manuseio de incidentes deve identificar recursos e ações afetados através de registros de auditoria seguros, e então examinar como o valor escapou para que o caminho de entrega possa ser corrigido.

A expiração limita a vida de credenciais esquecidas. Uma validade curta é útil apenas se a renovação for automatizada e observada. Um sistema que silenciosamente substitui chaves expiradas por credenciais de emergência permanentes derrota o controle.

Monitoramento Sem Vazamento de Chaves

Os registros devem registrar um ID de chave não secreto, projeto, decisão, ponto final, classe de resposta, carimbo de data/hora e identificador de correlação de solicitação. Nunca escreva a chave completa. A censura deve ocorrer antes que os dados deixem o processo da aplicação e deve cobrir cabeçalhos, mensagens de exceção, rastros e pacotes de suporte.

Alerta sobre pontos finais, regiões, volume de tráfego, padrões de erro e uso de um ambiente que não corresponde ao propósito da chave. Carimbos de data/hora de último uso ajudam a encontrar chaves dormentes, mas a ausência de uso observado deve ser confirmada antes da revogação, pois a cobertura de monitoramento pode ser incompleta.

Erros Comuns de Chave API

• Uma chave para cada ambiente. Um vazamento de desenvolvimento pode então afetar a produção.
• Chaves em URLs. Strings de consulta se espalham através de registros, análises, histórico do navegador e referenciadores.
• Chaves em código de frontend. Clientes públicos não podem proteger um segredo compartilhado de longa duração.
• Credenciais permanentes sem restrições. Autoridade excessiva expande o impacto da exposição.
• Segredos completos nos logs. Sistemas centrais de observabilidade se tornam repositórios de credenciais.
• Sem proprietário ou propósito. Ninguém pode decidir se uma chave antiga ainda é necessária.
• Conversão de tipo automática silenciosa. Tratar uma chave como um número pode alterar caracteres iniciais ou a precisão; credenciais são strings opacas.

Quando usar uma chave de API

Conclusão

Uma chave de API é uma credencial direta para identificar um cliente de software ou projeto. A string em si é apenas uma parte do sistema. A segurança vem de uma geração de alta entropia, transporte TLS baseado em cabeçalhos, escopo restrito, armazenamento protegido, registro seguro, uso observado, rotação planejada e revogação imediata. As chaves de API se encaixam no acesso controlado à aplicação; elas não devem ser estendidas para um sistema de delegação de usuários ou incorporadas onde um cliente público possa expô-las.