Solución: La API REST o el Servidor MCP responden con error de autorización 401

Guía paso a paso para desarrolladores e integradores para diagnosticar y solucionar respuestas HTTP 401 Unauthorized al interactuar con la API REST v1 oficial o con el Servidor MCP de WaclisCAL.

1. Síntoma

Al realizar peticiones HTTP hacia los endpoints de la API REST v1 (/api/wacliscal/v1/...) o al conectar un cliente MCP (como Claude Desktop o Cursor), la respuesta devuelve un código de estado HTTP 401 Unauthorized acompañado de un mensaje JSON:

`{"success": false, "error": {"code": "UNAUTHORIZED", "message": "Token de autenticación faltante, inválido o revocado."}}`

2. Causas probables

El error 401 indica inequívocamente que la petición no superó la capa de validación criptográfica por:

1. Falta de la cabecera Authorization: No se incluyó la cabecera Authorization: Bearer [TOKEN] en los encabezados HTTP de la solicitud.
2. Formato incorrecto del prefijo Bearer: Se omitió la palabra Bearer, o se colocaron dos espacios entre Bearer y la clave.
3. Token revocado o eliminado: La clave de API fue revocada manualmente en el panel de control de WaclisCAL.
4. Token con fecha de caducidad superada: El token fue creado con un plazo de vencimiento temporal (ejemplo: 30 o 90 días) que ya expiró.
5. Token incompleto o con caracteres corruptos: Al copiar el token desde el panel, se omitieron caracteres finales o se copiaron espacios o saltos de línea invisibles.

3. Comprobaciones previas

1. Abre el gestor de tokens en WaclisCAL (Ajustes > Desarrollador > Tokens de API) y comprueba si tu token figura como Activo o Revocado / Expirado.
2. Verifica que la clave comience con el prefijo oficial de WaclisCAL (wcal_evt_live_... o wcal_evt_test_...).
3. Revisa la solicitud cURL o la configuración de tu cliente HTTP para inspeccionar las cabeceras exactas que se están enviando.

4. Solución paso a paso

Paso 1: Comprueba el formato exacto de la cabecera HTTP

1. Asegúrate de estructurar la cabecera de autenticación con el formato estándar:

Authorization: Bearer wcal_evt_live_tu_token_completo_aqui

1. Errores comunes a evitar:

- ❌ Authorization: wcal_evt_live_... (Falta la palabra Bearer).

- ❌ Authorization: Bearer: wcal_evt_live_... (No debe llevar dos puntos tras Bearer).

- ❌ Bearer: wcal_evt_live_... (El nombre de la cabecera debe ser Authorization).

Paso 2: Genera un nuevo token si fue revocado o expiró

1. Si tu token anterior fue revocado o caducó, no es posible reactivarlo.
2. En WaclisCAL, ve a Ajustes > Desarrollador > Tokens de API.
3. Haz clic en Crear nuevo token.
4. Asigna un nombre, selecciona los permisos y haz clic en Generar.
5. Copia el token completo de inmediato antes de cerrar la ventana modal.

Paso 3: Actualiza las variables de entorno en tu aplicación o cliente MCP

1. En tu backend o aplicación: Actualiza el archivo .env con la nueva clave (WACLISCAL_API_KEY=wcal_evt_...) y reinicia el servicio.
2. En Claude Desktop: Abre claude_desktop_config.json, actualiza la variable WACLISCAL_API_TOKEN con el nuevo valor y reinicia la aplicación.
3. En Postman: Abre la colección de WaclisCAL, ve a la pestaña Variables y actualiza el campo token con el nuevo valor.

5. Cómo verificar que quedó resuelto

1. Ejecuta una petición simple de prueba mediante curl en tu terminal:

curl -X GET "https://cal.waclis.com/api/wacliscal/v1/event-types" \
-H "Authorization: Bearer wcal_evt_live_tu_token_nuevo" \
-H "Accept: application/json"

1. La respuesta debe devolver un código de estado HTTP 200 OK con el listado JSON de tus Tipos de Evento.

6. Cuándo escalar el problema

Si el token es nuevo, está activo, el formato de la cabecera es correcto y el servidor sigue respondiendo 401:

• Comprueba si tienes un proxy inverso o firewall intermedio que esté filtrando o eliminando la cabecera Authorization antes de que llegue a WaclisCAL.
• Si utilizas una biblioteca cliente HTTP específica, verifica que no esté agregando codificaciones extrañas.
• Si persiste el inconveniente, contacta a soporte técnico de Waclis adjuntando los primeros 12 caracteres del token (ejemplo: wcal_evt_live_a1b2...) y el código de respuesta obtenido.

7. Artículos relacionados

• Genera y administra tokens de acceso seguros por Tipo de Evento
• Integra WaclisCAL con tus propios sistemas mediante la API REST v1 oficial
• Conecta tu agenda con asistentes de IA externos utilizando el Servidor MCP