Chaves de API – Criar, usar e revogar uma chave
As Chaves de API são credenciais de acesso programático, descritas pela plataforma como as credenciais para integrações externas. Elas permitem que sistemas seus acessem os dados de conformidade da sua organização.
Antes de qualquer coisa, uma informação que economiza tempo.
É um recurso do plano Enterprise
A plataforma é direta: o gerenciamento de chaves de API requer um plano Enterprise, e a tela orienta o contato para upgrade quando o plano não inclui.
Se você vê essa mensagem, não há configuração a fazer: é uma conversa comercial.
Para que serve, na prática
O estado vazio da tela resume o propósito: criar uma chave para permitir que sistemas externos acessem os seus dados de conformidade.
Os usos que realmente aparecem:
Levar dados de conformidade para o seu painel interno. Empresas que mantêm um painel executivo próprio querem o indicador de conformidade ali junto com os outros números.
Alimentar um data warehouse. Para análise histórica junto com dados de outras fontes.
Automatizar um fluxo interno. Por exemplo, abrir um chamado no seu sistema de tarefas quando um controle falha.
Alimentar um relatório recorrente para a diretoria ou o conselho.
Um contraponto honesto: para a maioria das empresas, isso não é necessário. A plataforma já tem painel, análises e relatórios. Chave de API faz sentido quando existe um sistema interno que precisa dos dados, e não como conveniência.
Criar uma chave
Use Criar Chave de API, informando:
Nome. Como a chave é identificada.
Permissões. O que ela pode acessar.
Sobre o nome, uma recomendação que vale muito depois: descreva o sistema que vai usar a chave, e não a data. *Painel executivo interno* é um bom nome; *Chave 1* não é. Em um ano, quando você estiver revisando as chaves ativas, o nome é a única coisa que permite decidir se ela ainda é necessária.
Sobre as permissões: conceda o mínimo. Uma chave que alimenta um painel de leitura não precisa de nada além de leitura, e o dano de uma chave vazada é proporcional ao que ela alcança.
O segredo aparece uma única vez
Este é o ponto crítico da tela. Ao criar a chave, a plataforma exibe o Client ID e o Client Secret, com um aviso explícito: salve este segredo agora, porque ele não poderá ser recuperado novamente.
Ou seja: se você fechar a janela sem copiar, a chave é inútil e o caminho é criar outra.
Como fazer isso direito:
Tenha o destino pronto antes de criar. Se o segredo vai para um cofre de senhas ou para a configuração de um sistema, abra isso antes.
Guarde no cofre corporativo, não em anotação. Chave de API em mensagem de conversa ou em planilha compartilhada é uma exposição séria, e é exatamente o tipo de achado que a própria plataforma sinaliza em outros contextos.
Copie os dois valores. O identificador e o segredo, porque os dois são necessários.
Revogar é definitivo
A ação de revogar pede confirmação e avisa que não pode ser desfeita.
Ao revogar, qualquer sistema que use aquela chave para de funcionar imediatamente. Então vale a sequência correta: primeiro atualize o sistema com uma chave nova, confirme que ele funciona, e só então revogue a antiga.
Quando revogar:
A integração que usava a chave foi desativada.
Houve suspeita de exposição. Nesse caso, revogue primeiro e trate as consequências depois. Chave possivelmente vazada em uso é pior que sistema momentaneamente parado.
A pessoa que criou a chave saiu e ninguém sabe onde ela é usada. É um caso desconfortável e comum, e a resposta certa é revogar e descobrir o que quebra.
Rotação periódica. Vale incluir na sua rotina anual.
A rotação, e por que ela importa em auditoria
Chaves de API são credenciais de longa duração, e credencial de longa duração sem rotação é um achado clássico.
Uma prática defensável:
- Rotacione as chaves ao menos uma vez por ano, ou conforme a sua política.
- Crie a nova, atualize o sistema, confirme, revogue a antiga. Nessa ordem, sem janela sem serviço.
- Registre a rotação. A data de criação de cada chave já está na lista, o que serve como evidência.
E a conferência mais valiosa é a mais simples: olhe a lista de chaves ativas uma vez por trimestre e pergunte, para cada uma, qual sistema a usa. Se você não souber responder, essa é a chave a investigar.
Sobre a documentação técnica
O uso da chave, com os endereços e o formato das respostas, é assunto técnico para quem vai integrar.
A referência técnica é fornecida pelo suporte para contas com o recurso habilitado. Vale solicitá-la junto com a habilitação, em vez de criar a chave e descobrir depois que falta a documentação.
Boas práticas resumidas
Uma chave por sistema. Chave compartilhada entre integrações torna impossível revogar uma sem quebrar as outras.
Nome que identifica o sistema.
Permissão mínima.
Guarde no cofre corporativo.
Rotacione periodicamente.
Revise a lista trimestralmente.
Os seis itens acima, além de boa prática, são exatamente o que um controle de gestão de credenciais espera. Aplicá-los aqui é conformidade, e não apenas cuidado técnico.
Problemas comuns
Recurso Enterprise. O gerenciamento de chaves exige plano Enterprise.
Falha ao criar chave de API. Tente novamente e confira o nome.
Perdi o segredo. Ele não pode ser recuperado. Crie uma chave nova e revogue a antiga.
Revoguei e um sistema parou. Era o comportamento esperado. Crie uma chave nova e configure o sistema.
Falha ao revogar a chave. Tente novamente.
Não sei se posso revogar uma chave. Se você não identifica qual sistema a usa, o risco de mantê-la costuma superar o de revogá-la. Vale avisar o time técnico e revogar.
Este artigo foi útil?