Runbook — Re-autorización OAuth Zoho tras cambio de scopes

Cuándo usar este runbook: siempre que se modifique ZOHO_SCOPES en functions/_lib/zoho.ts y haya que propagar los nuevos permisos a los refresh_token de los miembros del equipo.

Contexto

La integración Zoho de CreaRack Workspace usa OAuth 2.0 con offline_access (refresh tokens de larga duración). Los scopes se declaran en el momento del primer flujo de autorización y quedan fijados en el token. Si se añaden nuevos scopes a ZOHO_SCOPES, el token existente sigue siendo válido para los scopes anteriores, pero no incluye los nuevos hasta que el usuario complete de nuevo el flujo completo.

Historial de cambios de scopes

Problema que resuelve

Sin ZohoCalendar.event.UPDATE y ZohoCalendar.event.DELETE, los hooks del ciclo de vida de tasks fallan silenciosamente:

• Al cerrar una task: el evento auto_end_planned no se borra en Zoho → queda huérfano (existe en Zoho pero no en D1).
• Al cambiar due_date: el evento auto_end_planned no se mueve de fecha en Zoho.

El error no genera excepción visible porque la llamada a la API de Zoho devuelve 403 que se traga el handler. La tarea se gestiona correctamente en D1 pero el calendario de Zoho queda desincronizado.

Procedimiento de re-autorización

Pre-requisitos

• Tener sesión activa en el navegador con la cuenta de Google/Zoho correspondiente a cada miembro.
• Si el miembro tiene sesión en mail.zoho.eu de otro usuario, hacer logout primero (Zoho no permite multi-sesión en el mismo navegador y el token se asignaría al usuario equivocado).

Pasos (por miembro)

1. Abrir el navegador del miembro (o ventana de incógnito limpia).
2. Ir a la URL de inicio de autorización (ver tabla abajo).
3. Zoho pedirá login + aceptar los nuevos permisos del scope.
4. Tras el redirect de vuelta a workspace.crearack.com, la pantalla mostrará "Autorizado correctamente".
5. El nuevo refresh_token (con todos los scopes) queda guardado en D1 tabla zoho_tokens.

URLs por miembro

⚠️ Importante: hacer logout en mail.zoho.eu entre cada autorización cuando se autoricen usuarios distintos desde el mismo navegador de administrador.

Verificación post-re-auth

Tras re-autorizar, verificar que los nuevos scopes están activos creando o cerrando una task con due_date y comprobando que el evento en Zoho Calendar se borra/mueve correctamente.

Rollback

No hay rollback en sentido estricto: si la re-autorización falla o hay que deshacerla, el token anterior (solo READ/CREATE) sigue en D1 y puede restaurarse manualmente si se tiene backup. En la práctica, no re-autorizar simplemente mantiene el comportamiento anterior (hooks UPDATE/DELETE fallan silenciosamente).

Checklist

• Edu re-autorizado (ZohoCalendar.event.UPDATE + DELETE activos)
• Dani re-autorizado
• Txell re-autorizada
• Verificar en Zoho Calendar que no quedan eventos auto_end_planned huérfanos de antes del fix

Véase también

• [[entity—zoho—service—zoho-scopes]]
• [[workspace—que-es-workspace]]