A chave de API não é um detalhe técnico da integração, e sim um instrumento de pagamento. Quem tem a string do token gasta o seu saldo sem perguntas: o serviço verifica o valor em si, não a pessoa diante do teclado. O desenvolvedor conecta cobrança, números ou proxies via API e recebe um segredo que parece uma variável qualquer, mas na prática equivale a um cartão com acesso ao dinheiro da conta. Vamos ver onde ela mais vaza, onde guardá-la do jeito certo, como dividir os acessos entre tarefas e pessoas e o que fazer em caso de vazamento.

A chave equivale ao acesso ao saldo

O token de API não confirma identidade: ele confirma o direito de gastar. O sistema não pergunta quem enviou a requisição com esse valor, ele verifica apenas o valor. Se a string caiu nas mãos de um terceiro, para a API isso é uma requisição legítima comum: compra de número, aluguel de proxy, débito do saldo — tudo passa como uma operação normal da conta. Não dá para distinguir um roubo do uso próprio pela requisição em si, por isso a única defesa que funciona é impedir que o segredo vá parar em mãos alheias, e não tentar reconhecer a fraude depois.

Onde a chave não deve ficar

O segredo de acesso vaza de forma recorrente pelos mesmos canais. Repositório de código — uma string commitada às pressas para um teste fica no histórico de versões do repositório para sempre: apagar o arquivo em um novo commit não remove o valor de um snapshot anterior, e um repositório compartilhado ou público transforma esse achado em acesso alheio ao saldo em questão de minutos. Imagem de contêiner — um token embutido no arquivo de build ou passado como argumento de build fica gravado em uma camada da imagem e viaja com ela para qualquer registro, inclusive ambientes de teste com acesso mais frouxo que o de produção.

Código do lado do cliente da página — tudo o que o navegador recebe e executa pode ser lido por qualquer visitante nas ferramentas de desenvolvedor; um valor usado para chamar o servidor sem um backend intermediário aparece em texto aberto. URL da requisição — um segredo passado como parte do caminho ou de um parâmetro de query é copiado junto com o endereço para todos os lugares onde a URL se acumula: logs do servidor web e do proxy, histórico do navegador, cabeçalho Referer ao seguir um link e, às vezes, o próprio texto do erro, se o serviço devolver no diagnóstico a URL recebida por inteiro. O lugar certo para ele é o cabeçalho da requisição, não o caminho nem a string de parâmetros.

Onde a chave deve ficar

A regra básica é simples: o segredo não deve existir como texto dentro do código ou de uma configuração que vai para o repositório. O processo de trabalho lê o valor de variáveis de ambiente definidas no nível do servidor ou do orquestrador, e não de um arquivo ao lado do código-fonte. O arquivo de exemplo da configuração é commitado com valores vazios, e o arquivo com os tokens reais não entra no repositório — ele está na lista de caminhos ignorados. Para equipes com mais de um segredo e trocas frequentes, variáveis de ambiente não bastam: é preciso um armazenamento separado, que entregue o valor sob demanda, mantenha um registro de acessos e revogue o acesso sem mexer no código da aplicação.

Chaves separadas por tarefa e por pessoa

Um token para tudo é a simplificação mais comum e mais cara. Se o servidor de produção, um script de teste e uma integração de terceiros compartilham o mesmo valor, revogá-lo em caso de vazamento significa parar tudo de uma vez: o serviço em funcionamento cai junto com o ambiente de teste vulnerável, que foi justamente quem vazou. Vale separar os acessos pelo menos em dois eixos — por tarefa (produção, CI, desenvolvimento local, integração de parceiro) e por pessoa ou equipe com acesso. Assim, revogar um segredo é a resposta a um incidente específico, e não a paralisação de toda a cobrança. Um benefício adicional: pelo registro de uso de cada valor dá para ver qual tarefa está consumindo o saldo, e uma anomalia nos gastos é localizada na hora.

Rotação de chaves: planejada e de emergência

A rotação planejada é a emissão de um novo segredo e a revogação do antigo conforme um cronograma, e não depois de um incidente. A ordem para evitar parada: emitir o novo valor sem revogar o anterior; aplicá-lo na configuração do serviço e confirmar que as requisições passam com sucesso; só depois revogar o token antigo. Dois valores ativos ao mesmo tempo por um curto período de transição é uma situação normal, e a infraestrutura permite isso.

Em caso de suspeita de vazamento, a ordem se inverte: primeiro a revogação, depois a investigação. Revogue imediatamente a chave comprometida, mesmo sem certeza absoluta — a parada durante a emissão de um novo valor custa menos do que gastos alheios no seu saldo. Em seguida, consulte o histórico de operações do período em que o acesso pode ter sido comprometido e compare com o que o sistema realmente fez. Se o segredo estava guardado junto com outros acessos — a senha do mesmo servidor, o token de um serviço vizinho como a API de proxy — troque-os também: o canal de vazamento raramente se limita a um único valor. Para não esbarrar no limite de requisições depois de trocar a chave, veja o artigo limites e throttling da API.

Perguntas frequentes

O que fazer se a chave já apareceu em um repositório público?

Revogue imediatamente, mesmo que o commit com o segredo tenha sido apagado pelo commit seguinte — o repositório guarda todas as versões do arquivo, e a exclusão não remove o valor de um snapshot anterior. Emita uma nova chave, atualize a configuração do serviço e só depois de verificar mude o tráfego para ela; marque o valor antigo como revogado, e não apenas como não utilizado.

É possível emitir uma chave com permissões limitadas, em vez de acesso a toda a API?

Se o serviço suportar tokens com escopo limitado — por exemplo, apenas leitura do saldo, sem permissão de débitos —, use exatamente esses para as tarefas que não precisam de acesso total. Um valor limitado, caso caia em mãos erradas, também limita o dano possível.

Com que frequência trocar as chaves se não houve vazamentos?

A periodicidade depende do número de pessoas e sistemas com acesso: quanto maior o círculo, menor o intervalo seguro. Uma referência razoável é rotacionar pelo menos uma vez por trimestre os segredos de trabalho e imediatamente após a saída de qualquer pessoa que tinha o valor.

O formato de envio da chave no cabeçalho da requisição e os códigos de resposta em caso de revogação e de excesso de limite estão descritos na documentação da API de OTP.