Claves de acceso#

Una clave de acceso, también conocida como API key, es la credencial que una aplicación externa utiliza para autenticarse con Kivox. Cada clave pertenece a un espacio de trabajo y debe tratarse como un secreto: cualquier persona con acceso a ella puede utilizar las capacidades autorizadas para esa credencial.

#Crear una clave

Abra la configuración del espacio de trabajo, acceda a Claves de acceso y seleccione crear una nueva. Asigne un nombre que identifique claramente la aplicación o el entorno que la utilizará.

Aplicación web de producción
Backend de soporte
Integración móvil
Entorno de desarrollo

Evite nombres ambiguos como "Clave nueva" o "Test": una buena nomenclatura facilita la rotación y la auditoría posterior.

Opcionalmente, puede establecer una fecha de expiración y asignar alcances (scopes) que limiten las operaciones que la credencial puede realizar. Una integración que solo necesita trabajar con conversaciones no debería recibir permisos adicionales que no usa: una credencial debería representar una tarea, no una autorización global.

#El secreto se muestra una sola vez

El secreto se muestra una sola vez: al crear la clave, Kivox devuelve su valor en texto plano y debe almacenarlo inmediatamente en un lugar seguro, ya que, por diseño, no puede volver a consultarse ni recuperarse posteriormente.

Esta limitación responde a un criterio de seguridad: evitar que las credenciales puedan quedar expuestas o ser recuperadas posteriormente desde la aplicación, reduciendo así el impacto de un acceso no autorizado. Kivox tampoco tiene capacidad para consultar ni recuperar estas credenciales después de su creación.

#Rotación

La rotación es recomendable cuando una credencial ha sido expuesta o como parte de una política periódica de seguridad.

Mantener un breve período en el que ambas claves sean válidas facilita una transición sin interrupciones. No espere a que una credencial expire durante una operación crítica.

#Diagnosticar un error de autenticación

Cuando una integración devuelve un error de autenticación, verifique en orden: que la clave pertenece al espacio de trabajo correcto, que la variable de entorno de la aplicación contiene el valor esperado, que la aplicación está usando la clave vigente y no ha expirado, y que los alcances asignados permiten la operación que intenta realizar.

Si el problema persiste, conserve el identificador de solicitud (request_id) de la respuesta de error. Es la referencia más útil para diagnosticar un fallo puntual, tanto internamente como al contactar soporte.

#Guardar una clave de acceso de forma segura

Una clave de acceso debe considerarse un secreto y mantenerse fuera del código fuente, los repositorios y los artefactos que puedan quedar expuestos.

#¿Qué puede suceder si una clave de acceso se filtra?

Una clave de acceso expuesta puede ser utilizada por terceros para autenticarse como la aplicación o integración a la que pertenece. El impacto dependerá de los permisos asociados a la credencial, pero puede incluir:

• Acceso no autorizado a las capacidades y recursos permitidos por sus scopes.
• Lectura, modificación o eliminación de datos cuando la clave tenga permisos para realizar esas operaciones.
• Uso de recursos que puedan generar costos para el propietario del espacio de trabajo.
• Abuso de la API, generación de tráfico inesperado o agotamiento de límites de uso.
• Exposición de información asociada al espacio de trabajo o a las integraciones autorizadas.
• Dificultades para determinar el origen del acceso si la misma clave se utiliza en varias aplicaciones o entornos.

Una clave de acceso no debería considerarse segura simplemente porque su valor tenga un formato difícil de adivinar. Si el secreto llega a manos de un tercero, debe asumirse que puede utilizarlo hasta que la credencial sea revocada.

Por este motivo, una clave sospechosa de haber sido expuesta debe retirarse y sustituirse por una nueva. La rotación permite invalidar la credencial comprometida y limitar el período durante el cual puede ser utilizada. Siempre que sea posible, revise también los registros de acceso y determine cómo se produjo la exposición para evitar que vuelva a ocurrir.

#Almacenamiento en desarrollo

Para desarrollo local, puede utilizar variables de entorno y un archivo .env que no se incluya en el control de versiones:

KIVOX_API_KEY=sk_live_...

El archivo .env debe estar incluido en .gitignore y nunca debe compartirse mediante repositorios, tickets, mensajes de chat o registros de CI/CD.

No incluya la clave de acceso directamente en el código:

// Incorrecto
const apiKey = "sk_live_..."; // [!code error]

// Correcto
const apiKey = process.env.KIVOX_API_KEY; // [!code focus]

Las variables de entorno son un mecanismo para inyectar el secreto en la aplicación; no sustituyen a un sistema de gestión de secretos. En producción, es preferible utilizar un gestor de secretos que controle quién puede acceder a cada credencial y registre los accesos.

#Almacenamiento en producción

Para producción, utilice un gestor de secretos o el mecanismo equivalente proporcionado por la infraestructura donde se ejecuta la aplicación. La aplicación debería recuperar la credencial mediante una identidad de servicio o un mecanismo de acceso equivalente, en lugar de almacenarla en el código o en archivos incluidos en el despliegue.

Aplique, como mínimo, estas prácticas:

• Asigne una credencial diferente para cada aplicación y entorno.
• Conceda únicamente los scopes necesarios para la operación que realizará la aplicación.
• No registre la clave de acceso en logs, mensajes de error, métricas, trazas ni URLs.
• Evite introducir secretos directamente en comandos que puedan quedar almacenados en el historial de shell o en registros de CI/CD.
• Mantenga separadas las credenciales de desarrollo, staging y producción.
• Restrinja el acceso al gestor de secretos mediante identidades de servicio y el principio de mínimo privilegio.
• Rote la credencial cuando exista sospecha de exposición y establezca una política de rotación periódica cuando sea viable.

#Alternativas para gestionar secretos

#Qué hacer si una clave de acceso se expone

Ante una posible filtración o sospecha, no espere a confirmar que la credencial haya sido utilizada. Trátela como comprometida y siga el procedimiento de rotación:

Mantener durante un período breve la clave anterior y la nueva permite actualizar la aplicación sin interrupciones. Una vez verificada la nueva credencial, retire la anterior.

También debe revisar dónde se produjo la exposición. Una clave de acceso puede terminar accidentalmente en un repositorio, un archivo de configuración, un registro de CI/CD, una captura de pantalla, una traza o un mensaje compartido. Eliminar el secreto del archivo visible no garantiza que haya desaparecido del historial o de otros sistemas donde pudo haber sido almacenado.

La mejor protección es reducir el alcance de cada credencial, mantenerla fuera del código y proporcionar a cada aplicación únicamente los permisos que necesita.