Resumen
Una clave de API permite que un sistema externo se autentique ante la Safety App y trabaje con los datos de tu cuenta de forma programática. Creas una clave, copias su valor una única vez en el momento en que se genera, y se la entregas al sistema que la necesita. A partir de ahí, la clave se puede renombrar, desactivar, o revocar desde la configuración de claves de API, donde también puedes ver cuándo se usó cada una por última vez. Este artículo cubre cómo crear claves, leer la lista, y retirarlas de forma segura.
Introducción
Algunas integraciones no están cubiertas por las conexiones incorporadas. Puede que quieras llevar datos de incidentes a una herramienta de inteligencia de negocio, cargar registros desde otro sistema, o automatizar una tarea que no tiene una opción prediseñada. Una clave de API es lo que hace eso posible: identifica a un sistema externo concreto y le permite actuar sobre tu cuenta sin que una persona inicie sesión.
Las claves de API las gestionan los Admin y los Super Admin. Como una clave conlleva el mismo nivel de acceso que un usuario Admin, esto es tanto una tarea de seguridad como de configuración, y por eso este artículo dedica tanta atención a retirar claves como a crearlas.
Conceptos clave
- Clave de API: una credencial que permite a un sistema externo autenticarse ante la Safety App en nombre de tu cuenta. Otorga acceso programático con los mismos permisos que un usuario Admin, y por eso debe protegerse como una contraseña.
- Name: la etiqueta que le das a una clave para saber después para qué sirve. Como el valor de la clave nunca vuelve a mostrarse, el nombre es la única pista legible sobre qué sistema depende de ella.
- Prefix: los primeros caracteres de la clave, mostrados en la lista. Te permite emparejar un valor guardado en otro sistema con la fila correcta aquí sin exponer el secreto completo.
- Status: si la clave está Active o Inactive. Las solicitudes hechas con una clave inactiva son rechazadas.
- Last Used: cuándo se autenticó por última vez una solicitud con esa clave. Este es el campo que te dice si una clave sigue cumpliendo una función o quedó olvidada.
- Expires: la fecha de vencimiento, si se estableció una. Un vencimiento obliga a una rotación en lugar de dejar una clave válida indefinidamente.
Pasos a seguir
Abre la configuración de claves de API
Inicia sesión como Admin o Super Admin, abre Settings, luego el grupo Integrations, y luego API Keys. La página lista todas las claves de la cuenta con su nombre, prefijo, estado, último uso, vencimiento, y fecha de creación. Al final del panel se muestra una referencia de uso, útil para quien esté conectando el sistema que hará las llamadas.
Leyenda: Inicia sesión como Admin o Super Admin, abre Settings, luego el grupo Integrations, y luego API Keys.
Crea una clave
En el campo situado en la parte superior del panel de API Keys, escribe un Name que indique qué sistema usará la clave y qué hace, y luego selecciona Create API Key. Se abre un diálogo que muestra el valor completo de la clave.
Copia la clave ahora y guárdala donde corresponde: un gestor de contraseñas, una bóveda de secretos, o el almacén de secretos de tu sistema de compilación. El valor completo se muestra solo esta vez. La Safety App conserva un hash unidireccional en lugar de la clave misma, así que nadie —tampoco el equipo de soporte— puede recuperarla después. Si se pierde el valor, el único remedio es revocar esa clave y crear un reemplazo.
Maneja la clave con seguridad
Trata la clave como una contraseña, porque funciona como una. No la pegues en un correo ni en un chat, no la subas al control de versiones, y no la incrustes en ningún lugar desde donde se entregaría a un navegador o a una aplicación móvil donde un usuario pudiera leerla. Dale a cada integración su propia clave en lugar de compartir una entre varios sistemas: cuando una clave se comparte, revocarla para resolver un problema en un sistema deja fuera de servicio a todos los demás al mismo tiempo.
Lee la lista para detectar claves que ya no necesitas
La columna Last Used es lo más útil de esta página para la higiene continua. Una clave que no se ha usado en un mes suele ser la clave de una integración que ya se retiró, y cada clave así es acceso que existe sin motivo. Revisa la lista cada mes y revoca todo lo que ya no tenga un propósito. La columna Prefix ayuda aquí: te permite confirmar a qué fila corresponde un valor almacenado antes de actuar sobre ella.
Renombra y desactiva una clave
Selecciona el icono de edición junto a una clave para renombrarla. Renombrar no cambia nada del valor de la clave ni de sus permisos, así que es seguro hacerlo en cualquier momento y conviene hacerlo en cuanto un nombre deje de describir la realidad.
Selecciona el interruptor para desactivar una clave sin borrarla. Las solicitudes que usen una clave desactivada se rechazan de inmediato, pero la fila permanece en la lista para fines de auditoría, y puedes reactivarla más tarde. La desactivación es la herramienta adecuada cuando sospechas un problema pero aún no tienes certeza de a qué sistema pertenece una clave: detiene el acceso al instante mientras deja el registro intacto y la decisión reversible.
Revoca una clave y rota a un reemplazo
Selecciona el icono de eliminación para revocar una clave de forma permanente. Todo lo que siga usándola pierde la capacidad de autenticarse inmediatamente, y la revocación no se puede deshacer.
Para rotar una clave sin interrupciones, crea primero el reemplazo, actualiza el sistema que la consume para que use el nuevo valor, confirma que la clave nueva funciona, y solo entonces revoca la antigua. Rota según un calendario y no únicamente en emergencias, y rota de inmediato cuando alguien con acceso a una clave deje el equipo. Establecer una fecha de vencimiento en las claves usadas por sistemas automatizados convierte esa rotación en algo que la cuenta exige, en lugar de algo que una persona tiene que recordar.
Conclusión
Crear una clave de API es rápido; el cuidado está en lo que viene después. Nombra cada clave según el sistema que la usa, copia el valor una sola vez en un almacenamiento de secretos adecuado, mantén una clave por integración, y usa la columna Last Used para encontrar accesos que ya sobrevivieron a su propósito. Cuando haya que eliminar una clave, desactívala si necesitas una detención reversible y revócala cuando tengas certeza, creando siempre el reemplazo antes de quitar la clave que todavía está en servicio.