Rotação

Rotacionar é trocar o segredo sem trocar a integração. A API gera uma chave nova com a mesma configuração e deixa a antiga respondendo por um tempo, para você trocar o segredo nos seus sistemas sem derrubar nada.

Quando rotacionar

Quando alguém que tinha acesso à chave sai da equipe ou do fornecedor.
Quando a chave passou por um lugar que você não controla: chamado, conversa, log, captura de tela, máquina emprestada.
Quando você troca de servidor, de provedor ou de ferramenta de implantação.
Em intervalo regular, se você quiser essa rotina.

Não existe prazo obrigatório aqui, e a API não força nenhum. Se você quer uma rotina simples de manter, escolha um prazo de expiração na criação da chave (30 dias, 90 dias ou 1 ano) e trate a data como o lembrete de rotacionar.

Se você suspeita que a chave vazou, o caminho não é a convivência: é parar a chave antiga na hora. Veja Boas práticas de chave.

O que a rotação copia

Copia da chave antiga: o nome, as permissões, o membro representado, a lista de IPs e a data de expiração.

Não copia: o segredo, que é novo; o registro de uso; as chaves de idempotência.

O registro de uso fica com a chave que fez cada chamada. A chave nova começa com a lista vazia em Ver uso, e o histórico da antiga continua na antiga.

A convivência

No painel: menu da chave, Rotacionar. O formulário pede a sua senha, e só OWNER e ADMIN rotacionam. Você escolhe por quanto tempo a chave antiga continua valendo.

Escolha	O que acontece com a chave antiga
Parar agora	Revogada na mesma ação. A chamada seguinte com ela recebe 401
1 hora	Continua respondendo por 1 hora e para sozinha no fim do período
24 horas	Continua respondendo por 24 horas e para sozinha no fim do período

Durante a convivência as duas chaves respondem, e a antiga fica com o estado Em rotação no painel. Você não precisa esperar o período acabar: revogue a antiga assim que confirmar a troca.

Os endpoints de webhook inscritos pela chave antiga seguem a rotação: com 1 hora ou 24 horas, eles passam para a chave nova na mesma ação e continuam recebendo; com Parar agora, eles são pausados, e dono e administradores recebem por e-mail a lista para revisar, porque quem pegou a chave pode ter cadastrado um endpoint. No painel, o endpoint pausado mostra o motivo “Pausado por segurança” (na API, disabled_reason: "emergency_key_rotation"), e religar pede a sua senha. Veja Webhooks.

Passo a passo

Rotacione escolhendo o período de convivência.
Copie a chave nova. Ela também aparece uma vez só.
Troque o segredo nos seus sistemas.
Confirme com uma chamada a GET /public/v1/me usando a chave nova e compare o key.prefix da resposta com o prefixo que o painel mostra na chave nova. É assim que você sabe que o seu sistema está usando a chave nova, e não a antiga que ficou em algum cache.
Revogue a antiga.

As armadilhas

A chave nova herda a data de expiração da antiga. Rotacionar uma chave que expira semana que vem devolve uma chave que também expira semana que vem. Rotação troca o segredo, não renova prazo. Para ganhar prazo, crie uma chave nova.

A chave nova ocupa vaga na cota enquanto a antiga não morre. A cota de chaves do plano conta toda chave que ainda autentica, e a antiga em convivência ainda autentica. A rotação em si não é barrada pela cota, mas criar mais uma chave é, até a antiga ser revogada ou expirar. Se a empresa já está no teto, escolha Parar agora ou revogue a antiga assim que trocar.

A idempotência não atravessa a rotação. A chave de idempotência vale por chave de API. A mesma Idempotency-Key enviada com a chave nova é uma requisição nova, e não a repetição da anterior: se a primeira já tinha criado um registro, a segunda cria outro. Termine com a chave antiga o que estiver em andamento, ou espere a resposta antes de trocar o segredo. Veja Idempotência.

Chave já rotacionada não rotaciona de novo. Quem rotaciona duas vezes rotaciona a chave nova. Chave revogada ou expirada também não rotaciona: nesses casos o caminho é criar uma chave nova.

Uma data de expiração anterior ao fim da convivência vence a convivência. Se a chave antiga já expirava em 6 horas e você escolheu 24 horas, ela para em 6 horas.

Chave de membro suspenso não rotaciona. Reative o membro ou crie uma chave para outro membro.

Quem ficou para trás

Depois que a chave antiga para, a chamada feita com ela recebe o mesmo 401 de chave inválida, sem dizer que o motivo foi a rotação.

Quem diz é o painel: a tentativa aparece em Ver uso da chave antiga, com o endereço de onde ela veio e o horário. É assim que você encontra o sistema que ficou com o segredo velho.

OWNER e ADMIN recebem e-mail a cada rotação e a cada revogação.

Próximo passo

Boas práticas de chave: o que fazer se a chave vazou.
IPs permitidos: a chave nova nasce com a mesma lista.
Idempotência: por que a repetição não atravessa a rotação.