Llaves API
La pantalla donde se crean, se revisan, se vuelven a generar y se revocan las llaves con las que los sistemas externos se conectan con tu institución.
Acceso
- Menú: Integraciones > Llaves API.
- Ruta:
/integraciones/api-keys.
La tabla
| Columna | Contenido |
|---|---|
| Prefijo | Los primeros caracteres de la llave. Es lo único que se conserva de su valor: sirve para identificarla, no para usarla. |
| Nombre | Con qué se creó. Debería decir qué sistema la usa. |
| Estado | Activa (verde), Revocada (rojo) o Expirada (gris, cuando pasó su fecha de vencimiento). |
| Último uso | Cuándo fue la última vez que alguien la usó. Un guion significa que nunca se usó. |
| Creada | Fecha de creación. |
| Última rotación | Cuándo se volvió a generar por última vez. Guion si nunca se rotó. |
| Veces rotada | Cuántas veces se ha vuelto a generar a lo largo de su vida. |
| Acciones | Ver últimas llamadas, Revocar y Volver a generar. |
El listado trabaja contra el servidor, con 20 llaves por página, ordenadas de la más reciente a la más antigua. No hay buscador ni columnas ordenables en esta pantalla, y no hay exportación: es un listado corto por naturaleza — una institución sana tiene pocas llaves vivas.
Fíjate en "Último uso" cuando revises las llaves. Una llave activa que nunca se usó, o que no se usa hace meses, es una puerta abierta sin nadie del otro lado: lo que corresponde es revocarla.
Crear una llave
Botón Nueva llave (visible solo con permiso de crear).
| Campo | Tipo | Descripción |
|---|---|---|
| Nombre * | Texto | Qué sistema o integrador la va a usar. Por ejemplo, Call center Asistencia Total. |
| Descripción | Texto | Detalle libre para quien administre las llaves. Por ejemplo, Confirmación de citas desde el IVR. |
| Expira el | Fecha | Vencimiento. Si se deja vacío, la llave no vence nunca. |
* Campo obligatorio
Al pulsar Crear llave aparece la segunda pantalla del modal, la que muestra la llave completa.
La llave se muestra UNA sola vez
Esta es la parte crítica de todo el módulo. El valor completo de la llave se muestra en el momento en que se crea, y nunca más. No se puede volver a consultar, ni por soporte, ni desde la base de datos: el sistema guarda solo una huella. Si se pierde, no se recupera — hay que generar otra.
Por eso esa pantalla está deliberadamente blindada: no se cierra con la tecla Escape, ni haciendo clic por fuera, ni con un botón de guardar. La única salida es el botón Ya la copié, cerrar.
En ella encuentras:
- El aviso de advertencia del sistema.
- El campo Llave, en solo lectura, con el valor completo.
- El botón Copiar, que la deja en el portapapeles y avisa "Llave copiada al portapapeles.".
Cómo entregarla sin quemarla
- Ten listo el canal seguro antes de crear la llave, no después: un gestor de contraseñas compartido o un canal cifrado acordado con el integrador.
- Cópiala y pégala directamente allí. No la pegues en un correo, un chat, un ticket, un documento compartido ni un archivo de texto "temporal".
- Limpia el portapapeles copiando cualquier otra cosa después.
- No la escribas en este manual, en un instructivo interno ni en una captura de pantalla.
- Verifica que el integrador la recibió y funciona antes de cerrar el ticket.
Una llave pegada en un chat corporativo ya está comprometida, aunque el chat sea "interno" y aunque se borre el mensaje: quedó en los respaldos, en las notificaciones y en los dispositivos de todos los que estaban en el canal. Si eso pasa, la llave se rota. No hay término medio.
Ver las últimas llamadas
Icono de ojo: Ver últimas llamadas. Abre la bitácora de esa llave, de solo lectura:
| Columna | Contenido |
|---|---|
| Fecha | Cuándo llegó la solicitud. |
| Ruta | Qué operación se invocó. |
| Método | El verbo de la solicitud. |
| IP | Desde qué dirección de internet se usó la llave. |
| HTTP | Código de respuesta, en verde si fue exitosa y en rojo si no. |
| Resultado | El desenlace de la solicitud. |
Se muestran 20 llamadas por página, con Anterior y Siguiente. Si la llave nunca se usó: "Esta llave todavía no registra invocaciones."
La columna IP es la herramienta de detección de este módulo. Si una llave que solo debería usar el call center empieza a aparecer con direcciones desconocidas, o con un volumen que no corresponde, asume que se filtró y rótala de inmediato.
También conviene mirar los rechazos: una racha de respuestas en rojo puede ser el integrador con la llave mal copiada, o alguien probando llaves que no tiene.
Volver a generar (rotar) una llave
Icono de recarga: Volver a generar (visible con permiso de modificar, solo en llaves activas). Emite una llave nueva conservando el nombre, la descripción y el vencimiento de la misma fila, junto con su historial.
Antes de hacerlo, el sistema pide confirmación con este aviso:
La llave "…" DEJARÁ DE FUNCIONAR DE INMEDIATO en cuanto se genere la nueva. No hay período de gracia: cualquier sistema que todavía use la llave actual empezará a recibir error 401 desde ese instante. Antes de continuar, confirme que puede actualizar la llave nueva en el sistema que la usa.
Al confirmar, se abre la misma pantalla de la llave en claro —ahora titulada Llave rotada— con las mismas reglas: se muestra una sola vez.
No hay período de gracia, y es a propósito
En el instante en que se genera la llave nueva, la anterior deja de servir. No existe una ventana en la que ambas funcionen. Es deliberado: el motivo más común para rotar es sospechar que la llave se filtró, y una ventana de gracia serviría exactamente para que quien la robó siga usándola.
El integrador que siga usando la llave anterior recibirá un error que, del lado de él, se ve igual que una llave mal copiada. No hay forma de que él distinga una rotación de un error de digitación: la diferencia solo la sabe quien rotó. Por eso hay que avisar.
Cómo coordinar una rotación sin cortar el servicio
- Avisa al integrador con anticipación y acuerda la ventana y el canal seguro por el que le entregarás la llave nueva.
- Que tenga preparado el reemplazo de su lado, para aplicarlo apenas la reciba.
- Rota, entrega y pídele una prueba antes de dar por cerrada la coordinación.
- Si la integración no puede tolerar ni un minuto de corte, no rotes: crea una llave nueva, deja que el integrador migre a ella, verifica que ya la esté usando, y solo entonces revoca la anterior. Es la única forma de tener una ventana con las dos llaves vivas — a costa de que la vieja siga sirviendo mientras tanto, lo que no es aceptable si sospechas que se filtró.
Revocar una llave
Icono de papelera: Revocar (visible con permiso de anular, solo en llaves activas). Pide confirmación:
La llave "…" dejará de funcionar de inmediato. Cualquier integración que la use empezará a recibir error 401.
Al confirmar, la llave pasa a estado Revocada y avisa "Llave revocada.".
La llave no se borra: queda en el listado con su historial y su bitácora de llamadas, que es lo que permite investigar después qué hizo mientras estuvo activa.
Revocar no se deshace. No hay forma de reactivar una llave revocada: si se revocó por error, hay que crear una nueva y entregarla.
Qué hacer si una llave se filtra
Actúa en este orden:
- Rota o revoca la llave de inmediato. Es lo primero, antes de investigar: mientras la llave viva, quien la tenga puede seguir usándola. Si la integración puede parar, revoca; si no, rota y entrega la nueva.
- Revisa la bitácora de llamadas de esa llave: qué IP la usó, desde cuándo, qué operaciones ejecutó y cuáles tuvieron éxito.
- Verifica el daño en la operación. Hoy la API solo confirma citas, así que el impacto se ve en citas confirmadas que nadie del mostrador confirmó. Cruza las fechas sospechosas de la bitácora con la agenda, buscando confirmaciones por Integración externa.
- Deja constancia interna del incidente: cuándo se detectó, qué se hizo, a qué hora se cortó el acceso.
- Evalúa si hubo datos personales comprometidos. La operación de confirmación se invoca con el documento del paciente: si alguien usó la llave, tuvo esos documentos. Involucra a quien responda por protección de datos en tu institución, por lo que exige la Ley 1581 de 2012.
- Entrega la llave nueva solo por el canal seguro, y revisa por qué falló el anterior.
El sistema limita cuántas solicitudes por segundo puede hacer una misma dirección, precisamente para contener el daño de una llave filtrada. Es una contención, no una protección: la llave sigue siendo válida hasta que alguien la revoque.
Sobre el alcance de una llave
Hoy las llaves se crean sin restricción de alcance: no hay un selector para limitar qué puede hacer cada una. Con una sola operación disponible en la API, en la práctica todas las llaves pueden hacer exactamente lo mismo: confirmar citas.
Tenlo presente hacia adelante: si mañana se habilitan más operaciones por esta vía, las llaves creadas hoy también podrán usarlas, aunque se hayan entregado pensando solo en confirmar citas. Es una razón más para revocar las llaves que no se estén usando en lugar de dejarlas vivas "por si acaso".
Recomendaciones
- Una llave por integrador, nunca una compartida entre varios. Es lo único que permite revocar a uno sin dejar a todos por fuera, y saber cuál se filtró cuando aparezca una IP rara.
- Pon fecha de vencimiento siempre que puedas. Una llave que expira sola es una llave que no depende de que alguien se acuerde de revocarla.
- Revisa el listado cada tres meses: revoca lo que no se usa, confirma que cada llave activa siga teniendo dueño y que el nombre siga diciendo la verdad.
- Rota las llaves de forma periódica, no solo ante un incidente, y aprovecha para verificar que el canal de entrega y el contacto del integrador siguen vigentes.
- Nunca uses la misma llave en el ambiente de pruebas del integrador y en producción.
Así se ve la pantalla
Dirección en el sistema:
/integraciones/api-keys