Rotacionar a chave cria um segredo novo com as mesmas permissões e o mesmo ambiente. Com janela, as duas chaves valem ao mesmo tempo por alguns dias, e o parceiro troca o segredo sem a integração parar.
Antes de começar a rotacionar a chave de API
Quem pode rotacionar: quem tem a funcionalidade Chaves de API — Escrita. Entre os papéis padrão, ela vem com Administrador da Organização e Administrador.
A confirmação de segurança: rotacionar pede um código do aplicativo autenticador ou do seu e-mail.
Só chave ativa rotaciona. Chave vencida ou revogada não rotaciona: use Emitir nova chave.
Passo a passo para rotacionar a chave de API
Em Configurações › Integrações › Chaves de API, abra o menu ⋯ da chave e clique em Rotacionar. Numa chave A vencer, o botão Rotacionar também aparece na coluna Vencimento.
Em Motivo, escolha Vencimento próximo, Segredo perdido, Segredo comprometido ou Política interna.
Em Como trocar, escolha:
Com janela — as duas chaves valem até você desativar a anterior ou a janela acabar;
Corte imediato — a anterior deixa de valer agora, e a integração para até o parceiro usar o segredo novo.
Em Duração da janela, escolha 1, 3, 7, 14 ou 30 dias.
Escolha o Vencimento da chave nova.
Clique em Rotacionar com janela ou Rotacionar e cortar agora e digite o código da Confirmação de segurança.
Copie o segredo novo no painel Guarde o segredo agora e entregue ao parceiro.
Acompanhar a troca da chave de API
Uma faixa no topo da tela diz quando a chave anterior para de valer, com o botão Gerenciar rotação.
A chave anterior mostra Substituída por … e a nova, Substitui …. O Último uso de cada uma mostra se o parceiro já passou a usar o segredo novo.
Quando o parceiro já usa a chave nova, clique em Desativar agora na linha da anterior e confirme em Desativar a anterior.
Sem nada fazer, a janela fecha sozinha no prazo, e a chave anterior deixa de valer.
Regras da rotação da chave de API
A chave nova tem as mesmas permissões e o mesmo ambiente da anterior.
Uma rotação por vez em cada integração.
Segredo comprometido corta na hora: a chave anterior deixa de valer em até 60 segundos, sem janela.
A janela vai de 1 a 30 dias e nunca passa do vencimento das duas chaves. Ela pode ser estendida uma vez, pelo detalhe da chave.
Rotacionar vale mesmo com a conta no limite de 10 chaves ativas.
Mensagens ao rotacionar a chave de API
Esta chave não pode ser rotacionada. Só uma chave ativa, fora de outra rotação, pode. — termine a rotação em andamento, ou emita uma chave nova se esta venceu.
Esta integração já tem uma rotação em andamento. — gerencie a rotação existente.
Esta janela já foi estendida uma vez. — a janela não estende de novo; desative a anterior quando o parceiro trocar.
A janela precisa ter de 1 a 30 dias e caber antes do vencimento das duas chaves. — escolha uma janela menor.
Perguntas frequentes sobre rotacionar a chave de API
Como cancelo uma rotação?
No detalhe da chave, use Cancelar a rotação. A chave nova deixa de valer, e a anterior continua com o vencimento que já tinha.
O segredo vazou. O que faço?
Rotacione com o motivo Segredo comprometido. A chave anterior deixa de valer em até 60 segundos.