Rotacionar ou revogar uma chave de API

As chaves de API são tokens portadores de longa duração, portanto, rotacioná-las em um cronograma — e revogá-las imediatamente quando uma vaza — vale a pena ser feito corretamente. Este artigo aborda ambos os casos.

Rotacionar uma chave sem tempo de inatividade#

Rotação significa emitir uma nova chave antes de aposentar a antiga, para que não haja lacunas onde sua integração fique não autenticada.

1. Vá para Settings → API keys e clique em Generate key.
2. Dê à nova chave um nome que torne o propósito claro (ex: production-v2).
3. Escolha a mesma função (role) da chave que você está substituindo.
4. Copie o token — ele é exibido apenas uma vez.
5. Atualize sua variável de ambiente ou gerenciador de segredos com o novo token e faça o deploy.
6. Assim que a nova chave estiver ativa e confirmada como funcional (verifique a coluna Last used — ela deve mudar em minutos), retorne para Settings → API keys e clique em Revoke na chave antiga.

Mantenha a chave antiga ativa até ter certeza de que a nova está funcionando. Se você revogar cedo demais e o deploy não tiver sido propagado, o tráfego receberá erros 401s.

Revogar uma chave vazada imediatamente#

Se uma chave for exposta — enviada para um repositório público, vazada em logs, incluída em um pacote do lado do cliente — revogue-a primeiro, investigue depois.

1. Settings → API keys, encontre a chave pelo nome ou prefixo (o prefixo é visível na tabela, embora o token completo não seja).
2. Clique em Revoke. A revogação propaga para todas as regiões em até 60 segundos.
3. Emita uma chave de substituição e atualize seus segredos.
4. Verifique o carimbo de data/hora Last used na chave revogada para estimar por quanto tempo ela ficou exposta e se você precisa auditar atividades inesperadas.

As chaves revogadas são armazenadas na tabela com um selo revoked para que você tenha um registro. Elas não podem ser reativadas.

Atualizar segredos com segurança#

O padrão recomendado é armazenar chaves em variáveis de ambiente, não no código:

# .env.local (never committed)
ELIDO_API_KEY=elido_live_xxx...

import { ElidoClient } from "@elido/sdk";

const client = new ElidoClient({ apiKey: process.env.ELIDO_API_KEY! });

Para pipelines de CI, use o cofre de segredos da sua plataforma (GitHub Actions secrets, GitLab CI variables, etc.) e rotacione sempre que um membro com acesso deixar a equipe.

O que acontece com integrações ativas#

Quando você revoga uma chave, qualquer solicitação em andamento que já tenha enviado o token ainda será concluída — validamos no início da solicitação, não no meio da resposta. Solicitações que começam após a revogação retornam 401 Unauthorized. Os SDKs não tentam novamente em caso de 401 (isso criaria um loop), então sua integração começará a falhar imediatamente.

Planeje uma breve janela de sobreposição: mantenha a chave antiga ativa até confirmar que a nova está ativa em produção.

Solução de problemas#

401 em uma chave que acabei de criar. O token mostrado no momento da criação é a chave completa, incluindo o sufixo secreto. Se você copiou apenas o prefixo da tabela (ex: elido_abc123), isso não funcionará — o prefixo é apenas para exibição. Emita uma nova chave e copie o token completo.

O botão Revoke está faltando. A chave provavelmente já está revogada. Chaves revogadas exibem um selo revoked e nenhum botão de ação. Verifique se você está olhando para o workspace correto — as chaves têm escopo de workspace.

Janela de propagação de 60 segundos. Se você revogou uma chave e as solicitações ainda estão sendo bem-sucedidas por um momento, isso é esperado. Nossos nós de borda sincronizam a revogação via Redis pub/sub; o atraso no pior caso é de ~60 segundos.

A chave desapareceu da lista. Mantemos as chaves revogadas na tabela indefinidamente para fins de auditoria. Se não conseguir encontrá-la, verifique se não filtrou a lista — não há filtro apenas para ativos por padrão, mas uma busca de texto no campo de nome ocultará as linhas que não coincidem.