← Voltar ao blog

Tokens de API de Analytics São Credenciais, Não Identificadores

Um token de API concede acesso a dados. Trate-o como segredo com um ciclo de vida: exiba uma vez, armazene um verificador, limite permissões e permita revogação.

Um token de API não é um rótulo para um usuário ou site. É uma credencial: quem obtiver um token válido poderá agir como seu titular. Tratá-lo como identificador faz com que ele apareça em logs, URLs, capturas de tela de suporte e configurações permanentes que ninguém sabe como revogar.

As melhores práticas de segurança do OAuth 2.0, publicadas pela IETF em janeiro de 2025, atualizam o modelo de ameaças e as recomendações para implantações OAuth. Um token pessoal de API não é necessariamente um token de acesso OAuth, mas o mesmo princípio de engenharia se aplica: credenciais baseadas em posse precisam de proteção em trânsito, restrição ao serviço pretendido e autoridade limitada ao necessário.

Mostre o segredo uma única vez

Gere tokens com uma fonte criptograficamente segura de aleatoriedade e entropia suficiente para impedir tentativas práticas de adivinhação. Retorne o token completo apenas na criação; depois, armazene um prefixo não secreto para identificação e um verificador unidirecional para consultas futuras. Se o banco de dados for copiado, um verificador é mais seguro que uma credencial reutilizável em texto puro. Não trate um hash de uso geral como hash de senha: tokens de API devem ter alta aleatoriedade, enquanto senhas humanas precisam de uma função de hash deliberadamente lenta.

Deixe explícito na interface e na resposta da API que o token só será exibido uma vez. Depois que o usuário sair da tela de criação, ofereça revogar e emitir outro, não recuperar o segredo original. Nunca coloque tokens em parâmetros de consulta, URLs, eventos de analytics, relatórios de erro ou capturas de tela. URLs acabam no histórico do navegador, em cabeçalhos de referência, logs de proxy e chamados de suporte com mais facilidade do que cabeçalhos de autorização.

Envie a credencial no lugar certo

Para APIs HTTP, aceite tokens no cabeçalho Authorization por TLS. A RFC 6750 descreve tokens bearer como utilizáveis por qualquer pessoa que os possua e alerta que a exposição durante o armazenamento ou o transporte permite o uso indevido. Também desaconselha colocar credenciais bearer em parâmetros de consulta de URI, pois URLs costumam ser registradas em logs. Rejeite tokens em query strings e corpos de requisição, a menos que um protocolo exija outro transporte e exista um modelo de ameaças documentado.

No servidor, valide o token antes de processar a operação solicitada. Resolva titular e permissões em armazenamento confiável; não aceite do request um usuário ou proprietário de site como autoridade. Mantenha segredos fora de logs de aplicação, traces e mensagens de exceção. Quando for necessário correlacionar operações, registre o ID ou prefixo não secreto do token, nunca a credencial.

Limite, expire e revogue

Um token deve conceder o menor conjunto útil de permissões. Quando o produto permitir, deixe o usuário restringir o token a sites selecionados e a operações de leitura ou específicas. Não conceda silenciosamente acesso de gravação à conta inteira a um script que precisa buscar um relatório. As melhores práticas de segurança OAuth discutem a restrição de privilégios e de audiência dos tokens; isso também serve como referência de projeto quando uma API usa seu próprio formato opaco.

Ofereça expiração e revogação como controles essenciais. Prazos menores reduzem o período em que uma credencial vazada continua útil; a revogação responde a incidentes e mudanças de equipe ou integração. Se a rotação exigir um período de sobreposição, defina um limite claro e mostre qual token está ativo. A revogação deve valer no limite da API, não apenas ocultar o token do dashboard.

Na API programática do Monoid, os tokens mnd_live_… criados por usuários são opacos, retornados em texto puro uma única vez e armazenados como hashes SHA-256, com expiração opcional e revogação lógica. Esse desenho protege o valor original contra leitura do banco, mas não torna inofensivo um token ativo que vazou. Mantenha-o fora do controle de versão, da saída de CI, de bundles do navegador e do histórico compartilhado do terminal; em caso de exposição suspeita, emita outro token e revogue o antigo.

Torne o ciclo de vida testável

Teste o fluxo completo: criar, usar com as permissões esperadas, rejeitar token inválido ou expirado, revogar e confirmar que o mesmo token deixou de funcionar. Verifique que um token não atravesse contas ou sites e que todos os endpoints apliquem as mesmas regras de autenticação e autorização. Inclua verificações operacionais para garantir que os logs ocultem credenciais e que as respostas da API nunca retornem o token armazenado.

O ciclo de gestão de segredos inclui criação, controle de acesso, rotação, auditoria e revogação — não apenas armazenamento seguro. Um token de API só permanece seguro quando o sistema identifica seu titular, limita suas ações, detecta exposição sem registrar o segredo e consegue desativá-lo rapidamente.

Fontes

Comments

Loading comments…