Rotação de Chaves e Segredos

A AUP exige rotação periódica de credenciais. Este guia detalha como rotacionar cada tipo de chave sem downtime.

Na prática, a rotação do client_secret é um botão: Rotacionar, na aba Credenciais do API Dashboard. O secret anterior continua válido por 24 horas, justamente para você atualizar o cofre e reiniciar as aplicações sem interrupção.

Tipos de credenciais e cadência mínima

Credencial	Onde vive	Cadência obrigatória	Imediata em caso de...
client_secret (OAuth2 client_credentials)	Painel admin → API Keys	12 meses	Exposição em log, repo público, ticket; saída de pessoa-chave; mudança ambiental
Chave privada JWT ES256 (Private Key JWT)	Seu HSM ou secret manager	12 meses	Mesmo que client_secret
Webhook signing secret	Painel admin → Webhooks	12 meses (rotação com sobreposição ainda não disponível — ver abaixo)	Endpoint comprometido, dump de log do receiver
Certificado mTLS de cliente	Seu emissor de certificado interno	Antes da expiração (você define)	Comprometimento da chave privada

Padrão de rotação sem downtime

Para client_secret, a SignDocs Brasil mantém dois segredos aceitos simultaneamente durante uma janela de 24 horas. Padrão:

1. Rotacionar no painel admin → o novo segredo é exibido uma única vez; o antigo continua aceito.
2. Implantar o novo segredo no seu cofre e reiniciar os serviços que o mantêm em cache.
3. Confirmar uso pelo Último uso no painel e pelo Analytics da credencial.
4. Nada a revogar: o segredo antigo para de funcionar sozinho ao fim da janela.

Por tipo de credencial

client_secret OAuth2

Painel → API Keys → Selecionar credencial → "Rotacionar"

Recebe um novo client_secret. O client_id não muda — apenas o segredo.

O segredo anterior continua aceito por 24 horas a partir da rotação; a resposta e o e-mail de aviso trazem o horário exato em previousSecretExpiresAt. Depois desse horário, apenas o novo segredo autentica, automaticamente — não há nada a revogar.

Use a janela para atualizar seu cofre de segredos e reiniciar as aplicações que mantêm o segredo em memória. Se a suspeita for de vazamento e 24 horas for tempo demais, pause a credencial (abaixo), rotacione e reative: a pausa recusa qualquer token, inclusive os emitidos com o segredo antigo.

A rotação não invalida os access tokens já emitidos — eles valem os 15 minutos do expires_in. Para cortar o acesso imediatamente, pause ou revogue a credencial.

Chave privada JWT ES256 (Private Key JWT)

Para tenants que autenticam com Private Key JWT em vez de client_secret:

1. Gerar nova chave EC P-256 localmente: openssl ecparam -name prime256v1 -genkey -noout -out new-private.pem
2. Extrair a pública e publicá-la no seu JWKS (jwksUri), ou montar um JWKS inline.
3. No painel admin → credencial → Atualizar JWKS, informar o novo jwksUri ou jwksInline.
4. Passar a emitir as assertions com a nova chave.

A troca substitui o JWKS inteiro, e vale na hora. Não há sobreposição de 24 horas nesse modo — ela existe apenas para client_secret. Se você usa jwksUri, a forma de rotacionar sem downtime é publicar as duas chaves no seu próprio JWKS (cada uma com seu kid), apontar o painel para ele, e remover a antiga depois. Com jwksInline, planeje a troca.

Webhook signing secret

Ainda não disponível. Não existe endpoint nem botão de rotação de segredo de webhook, e a assinatura enviada é sempre única — o header X-SignDocs-Signature nunca carrega duas assinaturas. Para trocar o segredo hoje, apague o webhook e registre-o de novo (DELETE seguido de POST /admin/tenants/{id}/webhooks), aceitando a janela em que eventos podem falhar a verificação. Um fluxo de rotação com sobreposição está no roadmap.

Certificado mTLS de cliente

Os endpoints mtls-api.signdocs.com.br e mtls-api-hml.signdocs.com.br exigem certificado de cliente. A SignDocs Brasil aceita até 3 cadeias de certificação confiáveis por tenant — então rotação é por adição:

1. Gerar nova chave + CSR localmente.
2. Anexar a nova chave pública ao tenant via painel admin.
3. Cliente HTTP passa a usar a nova chave/cert.
4. Após validação, remover a chave antiga do tenant.

Certificado ICP-Brasil A1 do tenant (assinatura corporativa)

Não disponível. Não existe upload de .pfx de tenant no painel. Os Evidence Packs (.p7m) são selados com o certificado A1 da própria SignDocs Brasil, não com um certificado por tenant — a rotação desse certificado é operada por nós e não exige ação do integrador. Certificados ICP-Brasil de signatários são outra coisa: entram por assinatura no momento do ato (perfil DIGITAL_CERTIFICATE) e não são armazenados.

Parar uma integração: pausar, revogar ou kill switch

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

Ação	Onde	Alcance	Reversível?	Efeito
Pausar credencial	Painel → Credenciais → Pausar	Uma credencial (logo, só SANDBOX ou só PRODUCTION)	Sim — Reativar, mesmo client_id e mesmo segredo	Nenhum token novo; os já emitidos passam a receber 503 em até 60s
Revogar credencial	Painel → Credenciais → Revogar	Uma credencial	Não — não dá nem para rotacionar depois	Igual à pausa, permanente. Voltar exige uma credencial nova, com client_id diferente
Kill switch do tenant	Painel → Segurança → Kill Switches	O tenant inteiro, sandbox e produção	Sim	Todas as chamadas /v1 respondem 503 e o /oauth2/token recusa, em até 60s

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

Mudanças de pausa e de kill switch levam até 60 segundos para valer em todas as instâncias — a configuração é cacheada por container de Lambda.

Só um MASTER do tenant pode rotacionar, pausar ou revogar uma credencial de produção; um DEVELOPER continua fazendo tudo isso em sandbox.

Princípio do menor privilégio

Use chaves separadas por aplicação, ambiente e função:

prod/api-server/client_id   ←  servidor backend, escopos completos
prod/cron-job/client_id     ←  job batch, escopos limitados a transactions:read
hml/api-server/client_id    ←  HML
hml/integration-tests/client_id  ←  CI, escopos mínimos

Comprometimento de uma só limita o blast radius. Vetor comum: chave de produção em commit publico → atacante exfiltra evidências de meses. Mitigação: keys de menor privilégio + rotação imediata + monitoramento Last-Used no painel.

Detecção de exposição

O que existe hoje é observabilidade, não automação:

• Último uso e Analytics por credencial no painel — GET /admin/tenants/{id}/credentials/{clientId}/analytics

mostra volume, taxa de erro e endpoints mais chamados. Um pico de 401 ou um Último uso que não bate com sua janela de operação são os sinais práticos de uso indevido.

• Logs de requisição por tenant (aba Logs / GET /admin/tenants/{id}/api-logs) — o

registro durável do que uma credencial realmente tentou.

• E-mail de aviso para o contactEmail do tenant a cada criação, rotação, pausa e

reativação de credencial. Se você receber um desses e não reconhecer a ação, pause a credencial e escreva para security@signdocs.com.br.

Não há varredura de segredos vazados no GitHub, revogação preventiva automática, nem fluxo de "rotação de emergência" com 2FA elevado. Detecção e reação são suas, com as ferramentas acima.

Reportar suspeita de exposição

security@signdocs.com.br. Inclua:

• client_id afetado
• Vetor suspeito (commit, log, ticket, ex-funcionário)
• Janela de tempo provável
• Se a credencial já foi rotacionada por você

A SignDocs Brasil ajuda na análise de logs para confirmar uso indevido. Inclui auditoria documental para Enterprise se exigida.

Cross-references

• runbooks/tenant-credentials.md — procedimento interno: provisionar, pausar, revogar e restaurar
• aup.md §5 — credenciais como confidenciais, princípio do menor privilégio
• webhooks-guide.md — verificação HMAC e overlap window
• signdocs.com.br/divulgacao-responsavel.html — divulgação responsável (chaves de terceiros expostas que afetam SignDocs Brasil)