A chave API é a credencial com a qual seus sistemas se autenticam na API da Whalemate. Este artigo explica onde ela é gerada, como é usada, o que habilita e como é revogada. Os endpoints de cada API estão em seus próprios artigos.
Autenticar as chamadas dos seus sistemas à API da Whalemate.
Integrar a folha de pagamento, as inscrições e os eventos de segurança com suas próprias ferramentas.
Cortar o acesso de uma integração pontual sem afetar as demais, se você deu uma chave própria para cada uma.
Esta funcionalidade é habilitada por empresa. Se em Configuración → Integraciones você não vê o cartão Claves API, escreva para nós e nós a habilitamos na sua conta.
Navegação: Configuración → Integraciones → cartão Claves API → botão Claves Activas
Abre-se a listagem Claves Activas com as chaves que você já tem.
Clique em Agregar nueva. Abre-se Nueva Clave API.
Preencha a Descripción. É obrigatória, e convém colocar o nome do sistema que vai usar a chave: é a única coisa que você vai ver depois para distinguir uma chave de outra.
Clique em Crear Clave.
A chave aparece completa, com um botão para copiá-la.
A chave é exibida uma única vez. O próprio diálogo avisa: «Esta clave API se muestra solo una vez. Cópiala y guárdala de forma segura en un lugar protegido. Si la pierdes, deberás generar una nueva clave.» Copie-a e guarde-a antes de fechar o diálogo.
A chave viaja no cabeçalho X-API-KEY de cada chamada:
X-API-KEY: tu_clave_api
Se a chamada não leva o cabeçalho, a API responde 401 com API Key required.
Se a chave não existe ou foi revogada, responde 403 com Invalid API Key.
Com uma chave válida, um sistema externo pode:
Consultar as inscrições em cursos e trilhas de aprendizagem.
Consultar as campanhas e seus eventos.
Consultar os e-mails reportados e sua análise.
Consultar, criar, modificar e excluir colaboradores.
Consultar, criar, modificar e excluir grupos.
Registrar eventos personalizados de segurança.
Uma chave habilita tudo isso junto. Não é possível gerar uma chave somente leitura, nem limitá-la a uma parte da API. Trate-a como uma credencial de administrador: guarde-a como você guarda uma senha de sistema, não a cole em um repositório nem em um ticket, e dê uma chave diferente para cada sistema que se integre. Assim, no dia em que precisar cortar o acesso de um, você revoga sua chave sem tocar nas dos demais.
A listagem tem duas colunas e uma ação:
Clave — mostra apenas os últimos 5 caracteres, precedidos de pontos. A chave completa não pode ser vista novamente na plataforma.
Descripción — a que você escreveu ao criá-la.
O ícone de lixeira da linha revoga essa chave.
As chaves não expiram. Uma chave continua válida indefinidamente até que você a exclua, então convém revisar a listagem de vez em quando e desativar as que correspondem a sistemas que você já não usa.
Mantenha as descrições atualizadas. É o único dado que permite saber a qual sistema corresponde cada chave, e sem ele você não vai conseguir decidir qual pode ser revogada.
Na listagem Claves Activas, clique no ícone de lixeira da linha. Aparece a confirmação «¿Estás seguro de que deseas eliminar esta clave API?».
Ao confirmar, a chave deixa de funcionar no momento. As chamadas que a usarem passam a receber um erro 403. Avise quem mantém essa integração antes de revogá-la, ou faça isso depois de tê-la substituído por uma nova.
Para rotacionar uma chave sem interromper o serviço: gere a nova, configure-a no seu sistema, verifique que as chamadas funcionam e só então revogue a anterior.
Perdi a chave. Posso vê-la novamente?
Não. A chave completa é exibida apenas ao criá-la. Gere uma nova, configure-a no seu sistema e depois revogue a anterior a partir da listagem.
As chaves expiram?
Não. Continuam válidas até que você as exclua.
Posso criar uma chave somente leitura, ou limitada a uma parte da API?
Hoje não: todas as chaves habilitam a mesma coisa. Se você precisar de permissões separadas por integração, escreva para nós e levaremos isso em conta.
Quantas chaves posso ter?
Não há um limite. A recomendação é uma por sistema, para poder revogá-las de forma independente.
Como sei se uma chave ainda está sendo usada?
A listagem não mostra o último uso, então a única referência é a descrição. Por isso convém escrever nela o sistema ao qual corresponde, e atualizá-la quando isso mudar.
Tem feedback ou quer solicitar melhorias? Nos avise em roadmap.whalemate.com/roadmap
Referência técnica para gerir colaboradores (colaboradores-alvo) a partir de sistemas externos: listar, criar, atualizar, eliminar e consultar o seu histórico de eventos de campanha através da API do Whalemate.
Referência técnica para consultar campanhas de simulação e seu histórico de eventos a partir de sistemas externos via API do Whalemate.