La clave API es la credencial con la que tus sistemas se autentican contra la API de Whalemate. Este artículo explica dónde se genera, cómo se usa, qué habilita y cómo se revoca. Los endpoints de cada API están en sus propios artículos.
Autenticar las llamadas de tus sistemas a la API de Whalemate.
Integrar la nómina, las inscripciones y los eventos de seguridad con tus propias herramientas.
Cortar el acceso de una integración puntual sin afectar a las demás, si le diste una clave propia a cada una.
Esta funcionalidad se habilita por empresa. Si en Configuración → Integraciones no ves la tarjeta Claves API, escríbenos y la habilitamos en tu cuenta.
Navegación: Configuración → Integraciones → tarjeta Claves API → botón Claves Activas
Se abre el listado Claves Activas con las claves que ya tienes.
Haz clic en Agregar nueva. Se abre Nueva Clave API.
Completa la Descripción. Es obligatoria, y conviene poner el nombre del sistema que va a usar la clave: es lo único que vas a ver después para distinguir una clave de otra.
Haz clic en Crear Clave.
La clave aparece completa, con un botón para copiarla.
La clave se muestra una sola vez. El propio diálogo lo 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.» Cópiala y guárdala antes de cerrar el diálogo.
La clave viaja en el encabezado X-API-KEY de cada llamada:
X-API-KEY: tu_clave_api
Si la llamada no lleva el encabezado, la API responde 401 con API Key required.
Si la clave no existe o fue revocada, responde 403 con Invalid API Key.
Con una clave válida, un sistema externo puede:
Consultar las inscripciones a cursos y a rutas de aprendizaje.
Consultar las campañas y sus eventos.
Consultar los correos reportados y su analítica.
Consultar, crear, modificar y eliminar colaboradores.
Consultar, crear, modificar y eliminar grupos.
Registrar eventos personalizados de seguridad.
Una clave habilita todo eso junto. No se puede generar una clave de solo lectura, ni limitarla a una parte de la API. Trátala como una credencial de administrador: guárdala como guardas una contraseña de sistema, no la pegues en un repositorio ni en un ticket, y dale una clave distinta a cada sistema que se integre. Así, el día que necesites cortarle el acceso a uno, revocas su clave sin tocar las de los demás.
El listado tiene dos columnas y una acción:
Clave — muestra solo los últimos 5 caracteres, precedidos por puntos. La clave completa no se puede volver a ver desde la plataforma.
Descripción — la que escribiste al crearla.
El ícono de tacho de la fila revoca esa clave.
Las claves no vencen. Una clave sigue siendo válida indefinidamente hasta que la elimines, así que conviene revisar el listado cada tanto y dar de baja las que correspondan a sistemas que ya no usas.
Mantén las descripciones al día. Es el único dato que te permite saber a qué sistema corresponde cada clave, y sin él no vas a poder decidir cuál se puede revocar.
En el listado Claves Activas, haz clic en el ícono de tacho de la fila. Aparece la confirmación «¿Estás seguro de que deseas eliminar esta clave API?».
Al confirmar, la clave deja de funcionar en el momento. Las llamadas que la usen empiezan a recibir un error 403. Avisa a quien mantenga esa integración antes de revocarla, o hazlo después de haberla reemplazado por una nueva.
Para rotar una clave sin cortar el servicio: genera la nueva, configúrala en tu sistema, comprueba que las llamadas funcionan y recién entonces revoca la anterior.
Perdí la clave. ¿Puedo volver a verla?
No. La clave completa se muestra únicamente al crearla. Genera una nueva, configúrala en tu sistema y después revoca la anterior desde el listado.
¿Las claves vencen?
No. Siguen siendo válidas hasta que las elimines.
¿Puedo crear una clave de solo lectura, o limitada a una parte de la API?
Hoy no: todas las claves habilitan lo mismo. Si necesitas permisos separados por integración, escríbenos y lo tenemos en cuenta.
¿Cuántas claves puedo tener?
No hay un límite. La recomendación es una por sistema, para poder revocarlas de forma independiente.
¿Cómo sé si una clave todavía se usa?
El listado no muestra el último uso, así que la única referencia es la descripción. Por eso conviene escribir en ella el sistema al que corresponde, y actualizarla cuando eso cambie.
¿Tienes feedback o quieres solicitar mejoras? Háznoslo saber en roadmap.whalemate.com/roadmap
Referencia técnica para gestionar empleados (colaboradores objetivo) desde sistemas externos: listar, crear, actualizar, eliminar y consultar su historial de eventos de campaña vía la API de Whalemate.
Referencia técnica para consultar campañas de simulación y su historial de eventos desde sistemas externos vía la API de Whalemate.