Crear y gestionar tus claves API
Genera claves API para conectar Joinways a tus herramientas vía la API REST, y gestiona sus permisos y revocación de forma segura.
Las claves API permiten que tus herramientas (sitio web, formulario de solicitud, software contable, automatizaciones externas) se comuniquen con Joinways de forma segura, vía la API REST. Cada clave es una credencial secreta que autentica tus solicitudes y actúa con los permisos que le otorgues.
Este artículo explica cómo crear una clave, ajustarla a los permisos adecuados, usarla en tus solicitudes y luego rotarla o revocarla. También sirve de referencia para los permisos y los estados de una clave.
Requisitos
Antes de crear una clave, asegúrate de cumplir las siguientes condiciones:
- Acceso de administrador: solo los administradores del espacio pueden crear, listar y revocar claves API.
- Un plan Pro: las claves API requieren el plan Pro; en otros planes la pestaña API permanece desactivada.
- Personas de confianza: una clave da acceso a tus datos, así que limita su creación y difusión a quienes realmente la necesiten.
Lo que vas a aprender
- Crear una nueva clave API desde tus ajustes
- Ajustar una clave a los permisos adecuados
- Usar la clave en tus solicitudes HTTP
- Rotar una clave sin interrupciones
- Revocar de inmediato una clave comprometida
Dos formas de conectar Joinways
Según tu herramienta, hay dos vías para conectar con Joinways. Elige la que se ajuste a tu caso.
- Conexión en un clic (MCP) : pega la URL del servidor MCP en tu asistente de IA y aprueba la conexión — sin token que copiar ni gestionar. Es la vía recomendada para asistentes compatibles.
- Clave API (REST) : para tus scripts, CLIs e integraciones a medida, vía la API REST (URL base /api/v1). Es el tema de este artículo.
Si tu herramienta no es un asistente de IA compatible con MCP, lo que necesitas es la clave API REST. El resto del artículo describe paso a paso su creación y uso.
Crear una clave
Crear una clave lleva menos de un minuto. La clave solo se muestra una vez, al crearla: cópiala antes de salir de la pantalla.
- Abre Ajustes y luego Integraciones, pestaña API.
- Haz clic en Nueva clave, ponle un nombre claro (p. ej. «Sitio web») y una caducidad.
- Revisa los permisos otorgados antes de confirmar (consulta la sección dedicada más abajo).
- Copia la clave mostrada de inmediato: solo se muestra una vez.
- Guárdala en un gestor de secretos, nunca en texto plano en tu código.
⚠️ Importante: una clave perdida no puede volver a mostrarse. Revócala y crea una nueva.
Ajustar la clave (permisos)
Antes de confirmar la creación, comprueba qué podrá hacer la clave. Una clave hereda los permisos que le otorgues: cuanto más amplios, más arriesgada es una fuga.
Da a cada clave los permisos mínimos que requiere su uso. Una clave destinada a mostrar tu disponibilidad en un sitio web, por ejemplo, no necesita poder modificar presupuestos.
Por lo general se distinguen los permisos de lectura (consultar datos) y de escritura (crear o modificar datos). Reserva la escritura para las integraciones que realmente la necesiten.
Usar la clave
Una vez que tengas la clave, preséntala en cada solicitud que envíes a la API de Joinways. Sin una clave válida, la solicitud se rechaza.
Añade la clave en la cabecera Authorization de tus solicitudes HTTP, como token Bearer: Authorization: Bearer <tu-clave>
Todas las solicitudes apuntan a la URL base /api/v1, seguida de la ruta del recurso (por ejemplo eventos o presupuestos).
- Construye la URL del recurso a partir de la URL base /api/v1.
- Añade la cabecera Authorization con tu clave como token Bearer.
- Envía la solicitud: una clave válida y autorizada devuelve los datos, de lo contrario un error de autenticación.
Rotar o revocar una clave
Rotar una clave consiste en reemplazarla por una nueva sin interrumpir el servicio. Planíficalo con regularidad, o en cuanto tengas una duda.
- Crea una nueva clave siguiendo los pasos anteriores.
- Despliega la nueva clave en tu integración.
- Comprueba que todo funciona con la nueva clave.
- Revoca la clave antigua una vez confirmado el cambio.
Para revocar una clave de inmediato (por ejemplo si está comprometida):
- Vuelve a Ajustes y luego Integraciones, pestaña API.
- Haz clic en Revocar junto a la clave correspondiente.
- La clave deja de funcionar de inmediato.
Referencia: permisos y estados de una clave
Esta sección resume los permisos que puede llevar una clave y los estados en los que puede encontrarse.
Permisos
- Lectura: permite consultar datos (por ejemplo listar eventos o presupuestos) sin poder modificarlos.
- Escritura: permite crear y modificar datos; resérvala para las integraciones que la necesiten.
- Alcance: una clave solo actúa dentro de tu espacio de trabajo y según los permisos otorgados al crearla.
Estados de una clave
- Activa: la clave es válida y aceptada por la API.
- Caducada: la fecha de caducidad ha pasado; la clave se rechaza hasta que se reemplace.
- Revocada: la clave se desactivó manualmente y ya no funciona, de forma definitiva.
Cómo funciona
En cada solicitud, la API lee la clave presentada en la cabecera Authorization y comprueba que esté activa, no caducada y no revocada.
Si la clave es válida, la API comprueba entonces que tenga los permisos necesarios para la acción solicitada y devuelve los datos.
Todas las acciones están vinculadas a tu espacio de trabajo: una clave nunca da acceso a los datos de otro espacio.
Casos particulares
- Varias integraciones: crea una clave distinta por integración en lugar de compartir una sola, para poder revocar una sin romper las demás.
- Clave sin caducidad: si tu integración funciona de forma continua, prevé igualmente una rotación regular para limitar la exposición.
- Cambio de equipo: cuando alguien deja el proyecto, revoca las claves que pudiera conocer y crea nuevas.
💡 Consejo: nombra tus claves según su uso («Sitio web», «Contabilidad», «Zapier») para identificar de un vistazo cuál revocar si algo falla.
Buenas prácticas de seguridad
Una clave API es un secreto, igual que una contraseña. Unas reglas sencillas reducen mucho los riesgos.
- Una clave por uso: más fácil de revocar sin romper todo.
- Nunca en texto plano: guarda tus claves en un gestor de secretos, no en el código ni en un repositorio Git.
- Nunca compartas una clave: por correo o chat; transmítela por un canal seguro si es necesario.
- Otorga los permisos mínimos: da acceso de escritura solo a las integraciones que lo necesiten.
- Caducidad y rotación: define una caducidad y revoca de inmediato cualquier clave sospechosa.
Solución de problemas
Estos son los problemas más frecuentes, su causa probable y la solución.
La solicitud devuelve un error de autenticación (401)
- Causa: la clave falta, está mal formada, caducada o revocada.
- Solución: comprueba la cabecera Authorization (token Bearer) y luego el estado de la clave en la pestaña API; si está caducada o revocada, crea una nueva.
La solicitud se rechaza (403) aunque la clave es válida
- Causa: la clave no tiene los permisos necesarios para la acción solicitada.
- Solución: usa una clave con los permisos necesarios (por ejemplo escritura para crear un dato), o vuelve a crear la clave con los permisos adecuados.
No se puede recuperar el valor de una clave existente
- Causa: una clave solo se muestra al crearla y nunca se guarda en texto plano.
- Solución: revoca la clave antigua y crea una nueva, y luego actualiza tu integración.
Ejemplos
Ejemplo 1 — Mostrar la disponibilidad en un sitio web
Creas una clave de solo lectura llamada «Sitio web», la guardas en el servidor de tu sitio y luego consultas la API para mostrar tus franjas disponibles. Si se filtra, la clave solo permite leer, nunca modificar tus datos.
Ejemplo 2 — Sincronizar una automatización
Creas una clave «Zapier» con los permisos que necesita, la pegas en tu herramienta de automatización y luego programas una rotación cada tres meses. El día que cambies de herramienta, revocas la clave antigua sin afectar a tus otras integraciones.
Preguntas frecuentes
¿Dónde encuentro la documentación de la API?
La referencia completa (endpoints, esquemas, ejemplos) está disponible en la referencia API de Joinways, accesible con el botón «Ver documentación» de la pestaña API o el enlace de abajo.
¿Las claves API están incluidas en todos los planes?
No: requieren el plan Pro.
¿Cuántas claves puedo crear?
Puedes crear varias claves, una por uso o integración. Incluso es recomendable, para poder revocar una sin afectar a las demás.
¿Qué pasa si pierdo una clave?
Una clave perdida no puede volver a mostrarse. Revócala y crea una nueva, y luego actualiza tu integración.
¿Una clave da acceso a los datos de otros espacios?
No. Una clave solo actúa dentro del espacio donde se creó y según los permisos que se le otorgaron.
¿Conviene rotar las claves con regularidad?
Sí, es una buena práctica. La rotación limita la exposición de una clave en el tiempo, incluso sin un incidente conocido.
¿Quién puede crear o revocar claves?
Solo los administradores del espacio de trabajo, con un plan Pro, pueden gestionar las claves API.
Véase también
¿Listo para centralizar tus solicitudes de eventos?