Rotação de credenciais sem downtime na API de assinatura

Rotação de credencial costuma ser adiada por um motivo razoável: ninguém quer descobrir, às três da tarde de uma terça, que trocar o segredo derrubou a integração. Na API da SignDocs Brasil isso é menos arriscado do que parece — o segredo anterior continua aceito por 24 horas depois da troca, então atualizar o cofre e reiniciar os serviços cabe numa janela confortável, e não há nada a revogar no fim. Mas a sobreposição tem limites que vale conhecer antes de precisar deles: ela não existe para todos os tipos de credencial, e não é o instrumento certo quando a suspeita é de vazamento.

As quatro credenciais, e quando cada uma vence

A cadência de 12 meses vem da política de uso aceitável. Na prática, o gatilho que mais aciona rotação não é o calendário — é alguém percebendo que o segredo apareceu onde não devia.

A rotação do client_secret, passo a passo

1. Rotacione no painel (Credenciais → selecionar → Rotacionar). O novo segredo é exibido uma única vez; o antigo continua aceito.
2. Implante o novo segredo no seu cofre e reinicie os serviços que o mantêm em memória.
3. Confirme o uso pelo campo Último uso da credencial e pelo Analytics dela — é assim que você sabe que os serviços realmente pegaram o valor novo.
4. Não faça nada no fim. O segredo antigo para de funcionar sozinho ao término da janela.

O horário exato do fim da janela vem em previousSecretExpiresAt, na resposta e no e-mail de aviso. Vale registrá-lo: é o prazo real para o seu rollout, e não "amanhã de manhã".

O que a rotação não faz

Esta é a parte que decide se o procedimento resolve o seu problema:

Rotacionar não invalida os tokens de acesso já emitidos. Um token vale os 15 minutos do expires_in dele, tenha sido emitido com o segredo antigo ou com o novo. Ou seja: depois da rotação ainda existe uma janela curta em que chamadas autenticadas com credencial antiga continuam funcionando.

Para uma troca planejada, isso é irrelevante. Para uma suspeita de vazamento, é o ponto inteiro — e a resposta correta é outra:

Pausar, revogar ou kill switch

Três controles com alcances muito diferentes. O erro caro é usar o mais forte por engano:

Regra prática: para parar a integração de produção sem parar o sandbox, pause a credencial de produção. Reserve o kill switch para o incidente que justifique derrubar tudo, e a revogação para credenciais que não devem voltar.

Duas propriedades operacionais dos três controles:

• Propagação de até 60 segundos. A configuração é cacheada por instância, então uma pausa não é instantânea em toda a frota. Num incidente, conte com esse minuto — e não conclua que o controle falhou ao ver uma chamada passar logo depois de acioná-lo.
• Produção exige papel MASTER. Um papel DEVELOPER faz tudo isso em sandbox sem depender de ninguém, mas não toca nas credenciais de produção. Vale conferir quem tem MASTER antes do incidente: descobrir no meio dele que ninguém disponível pode pausar a credencial é uma forma cara de aprender.

O kill switch tem alcances adicionais por método, e um artigo próprio: kill switch e degradação controlada.

As credenciais sem janela de sobreposição

A sobreposição de 24 horas existe apenas para o client_secret. Nos demais modos, a troca vale na hora — e a continuidade tem de ser construída do seu lado.

Chave privada JWT (ES256)

Para quem autentica com Private Key JWT em vez de segredo compartilhado, a atualização substitui o JWKS inteiro e passa a valer imediatamente. O caminho para rotacionar sem downtime é fazer a sobreposição você mesmo:

Com jwksUri isso funciona bem, porque o conjunto de chaves é seu. Com jwksInline não há como manter as duas conviverem pela via natural — planeje a troca para uma janela de baixa atividade.

Segredo de assinatura de webhook

Este é rotacionável pelo painel, na aba Webhooks — mas sem sobreposição: o segredo anterior é invalidado imediatamente, e o cabeçalho de assinatura nunca carrega duas assinaturas ao mesmo tempo.

A consequência prática é que existe uma janela curta em que eventos em trânsito podem falhar a verificação no seu receptor. Duas formas de conviver com isso:

• Rotacione em horário de baixo volume e aceite a janela, confiando na sua política de reprocessamento — eventos que falham verificação devem ser reprocessáveis, não descartados.
• Ou aceite temporariamente os dois segredos no seu verificador durante a troca: valide contra o segredo novo e, em caso de falha, contra o antigo, por um período curto e explicitamente datado no código.

A segunda opção é a que evita perda, desde que a tolerância seja removida depois — uma verificação que aceita dois segredos para sempre é uma verificação enfraquecida. O desenho do receptor está em webhooks em fila: ack rápido e reprocessamento.

Menor privilégio: uma chave por aplicação, ambiente e função

O ganho é o raio de alcance: uma credencial comprometida derruba uma aplicação, não a operação. O vetor clássico é a chave de produção esquecida num commit público, e o que a torna cara não é a exposição em si — é o escopo completo que ela costuma carregar. Uma credencial de leitura vazada é um incidente; a mesma credencial com escopos de escrita é outro tamanho de problema. O mapa de escopos está em por que o seu token falha.

O nome opcional da credencial no painel parece detalhe e não é: seis meses depois, "qual sistema usa esta chave?" é uma pergunta difícil de responder sem ele — e difícil de responder é o que atrasa uma rotação de emergência.

Detecção: o que existe, e o que não existe

Vale ser explícito sobre o limite, porque a expectativa costuma ser maior:

Existe observabilidade: o campo Último uso e o Analytics por credencial (volume, taxa de erro, endpoints mais chamados), os logs de requisição por tenant, e um e-mail para o contato do tenant a cada criação, rotação, pausa e reativação de credencial. Se chegar um desses avisos e ninguém reconhecer a ação, pause a credencial primeiro e investigue depois.

Os dois sinais práticos de uso indevido são um pico de 401 e um Último uso fora da sua janela de operação — uma credencial de job noturno usada às 15h, por exemplo.

Não existe: varredura automática de segredos vazados em repositórios públicos, revogação preventiva automática, nem um fluxo de "rotação de emergência" com autenticação reforçada. Detecção e reação são suas, com as ferramentas acima. Saber disso muda o desenho: se ninguém do seu lado olha o Analytics, ninguém está olhando.

Se suspeitar de exposição

Escreva para security@signdocs.com.br com o client_id afetado, o vetor suspeito (commit, log, chamado, ex-funcionário), a janela de tempo provável e se você já rotacionou. A análise de logs para confirmar uso indevido é feita em conjunto.

E faça a pausa antes de escrever o e-mail. Um minuto de indisponibilidade planejada custa menos que uma hora de acesso indevido.

Um roteiro para a primeira vez

1. Rotacione uma credencial de homologação primeiro, só para conhecer o fluxo e o formato do aviso.
2. Confirme quem tem MASTER no tenant e se essa pessoa está alcançável fora do horário comercial.
3. Separe as credenciais por aplicação e ambiente, se ainda estiverem compartilhadas.
4. Nomeie todas no painel.
5. Coloque a cadência de 12 meses no calendário — a rotação que não está agendada não acontece.
6. Escreva o procedimento de vazamento em uma página: pausar, rotacionar, reativar, e a quem escrever. É um documento que ninguém lê até precisar dele.

Para onde tudo isso acontece na interface, veja o painel de API. Para a passagem de homologação para produção, o checklist de go-live.

Perguntas Frequentes