Genera y administra tokens de acceso seguros por Tipo de Evento

Aprende a crear, configurar permisos y administrar el ciclo de vida de tokens de API seguros con prefijo oficial para conectar sistemas externos, aplicaciones móviles o asistentes de IA sin exponer la seguridad global de tu cuenta.

1. Qué permite hacer

La seguridad de las integraciones exige aplicar el principio del menor privilegio (least privilege): un sistema externo (como una aplicación de telemedicina o un bot de soporte) solo debe tener acceso a los servicios específicos que necesita operar, y nunca a toda la información confidencial de tu empresa.

WaclisCAL implementa un sistema granular de Tokens de Acceso por Tipo de Evento que te permite:

Generar claves de API criptográficas con prefijo reconocible:

- wcal_evt_live_...: Para entornos de producción operativos.

- wcal_evt_test_...: Para entornos de prueba o desarrollo.

Limitar el alcance (scope) del token a un único Tipo de Evento o a un grupo selecto de servicios.
Definir el nivel de acceso permitido: Solo lectura (consulta de disponibilidad y eventos) o Lectura y escritura (creación y cancelación de reservas).
Establecer fechas de caducidad automática opcionales para proyectos temporales o integraciones de terceros.
Revocar o eliminar tokens al instante ante cualquier sospecha de compromiso de seguridad sin afectar a otras integraciones activas.

2. Cuándo utilizarlo

Recomendamos generar tokens específicos en los siguientes escenarios:

Integraciones con desarrolladores externos: Al contratar a una agencia o programador externo para conectar tu sitio web, entrégale un token limitado exclusivamente al servicio que está integrando.
Conexión con asistentes de IA o MCP: Generar una clave dedicada para Claude Desktop o Cursor para auditar sus operaciones por separado.
Portales de clientes o apps móviles: Autenticar el backend de tu propia aplicación sin utilizar contraseñas maestras de administrador.
Automatizaciones en Make o n8n: Aislar cada flujo de trabajo con su propio identificador de seguridad.

3. Antes de comenzar

Antes de generar una nueva clave de API:

Contar con rol de Administrador en WaclisCAL.
Identificar el Tipo de Evento específico que requiere acceso programático.
Definir si la integración necesitará únicamente consultar horarios (read-only) o también confirmar turnos (read-write).

4. Paso a paso

Paso 1: Accede al gestor de tokens de API

En la barra lateral principal de WaclisCAL, haz clic en Ajustes.
En el menú de opciones, dirígete a Desarrollador y haz clic en Tokens de API (API Keys).
Verás la tabla con todos los tokens actualmente creados, su fecha de emisión, último uso y estado.

Paso 2: Inicia la creación de un nuevo token

Haz clic en el botón superior derecho Crear nuevo token.
Se abrirá la ventana modal de configuración de credenciales.

Paso 3: Asigna un nombre descriptivo y selecciona el alcance

Nombre del Token: Escribe una etiqueta clara que identifique el uso (ejemplo: "Integración App Móvil iOS" o "Make - Flujo Facturación").
Alcance de Servicios (Scope):

- Todos los eventos: Otorga acceso a todos los servicios de la cuenta (usar con precaución).

- Tipos de Evento específicos (Recomendado): Marca las casillas de los eventos autorizados (ejemplo: únicamente "Asesoría Comercial").

Permisos de Operación:

- Lectura (read): Permite listar eventos y consultar horarios disponibles.

- Lectura y Escritura (read:write): Permite además crear, reprogramar y anular citas.

Vencimiento (Opcional): Puedes definir si el token expira en 30 días, 90 días, 1 año o nunca (No expiration).

Paso 4: Genera y copia el token de seguridad

Haz clic en el botón Generar token.
El sistema mostrará la clave completa con su prefijo oficial (ejemplo: wcal_evt_live_7a8b9c0d1e2f3g4h5i6j7k8l9m0).
IMPORTANTE: Copia el token de inmediato y guárdalo en tu gestor de secretos seguro. Por razones criptográficas, WaclisCAL nunca vuelve a mostrar el valor completo del token una vez cerrada la ventana.
Haz clic en He guardado el token de forma segura.

Paso 5: Audita el uso y revoca accesos cuando sea necesario

En la lista de tokens, podrás ver la columna Último uso, que registra la fecha y hora exacta de la última petición HTTP recibida con esa clave.
Para revocar un acceso de inmediato:

- Haz clic en los tres puntos (...) junto al token.

- Selecciona Revocar token o Eliminar.

- Confirma la acción. A partir de ese segundo, cualquier petición que utilice ese token será rechazada con HTTP 401 Unauthorized.

5. Buenas prácticas de seguridad criptográfica

Prefijos identificables: El prefijo wcal_evt_... te permite buscar accidentalmente claves filtradas en repositorios de código mediante herramientas como GitGuardian o GitHub Secret Scanning.
Rotación periódica: Se recomienda renovar los tokens en producción al menos una vez al año.
Variables de entorno: Configura el token en variables de entorno en tu servidor (process.env.WACLISCAL_API_KEY o os.environ["WACLISCAL_API_KEY"]) y agrégalas al archivo .gitignore para evitar subirlas a GitHub o GitLab.
Un token por cada integración: Nunca reutilices la misma clave para dos sistemas distintos; la compartimentación evita que un fallo en un servicio afecte a los demás.

6. Problemas frecuentes

El token generado no permite crear reservas y devuelve error 403

Causa: El token fue creado con permisos de solo lectura (read) o el Tipo de Evento que intentas reservar no fue seleccionado dentro del alcance autorizado.
Solución: Revisa la lista de tokens, confirma qué servicios tiene asignados o genera un nuevo token con permisos de lectura y escritura (read:write).

Olvidé copiar el token y la ventana se cerró

Causa: Medida de seguridad criptográfica: el sistema solo almacena el hash del token en la base de datos, no el texto plano.
Solución: Revoca el token no guardado y genera uno nuevo, asegurándote de copiarlo antes de cerrar el modal.

7. Artículos relacionados

¿Necesitas más ayuda?

Si este artículo no resolvió tu consulta, nuestro equipo puede ayudarte personalmente.

Soporte por WhatsApp