Audita integraciones de terceros para fallos silenciosos

Por qué las integraciones de terceros fallan silenciosamente

Un fallo silencioso ocurre cuando una integración deja de hacer su trabajo pero nadie recibe un error claro. La app se carga. Los botones siguen funcionando. Aun así, el resultado nunca aparece: no hay mensaje en Slack, no hay evento en el calendario, no hay un check en GitHub, ni sincronización de datos.

La gente lo reporta como “antes funcionaba” porque la ruptura suele ser retrasada. Puede funcionar bien durante días o semanas y dejar de hacerlo cuando expira un token, cambia una política de permisos o alguien reinstala la app de forma distinta.

El impacto es fácil de pasar por alto porque parece que “no pasó nada”. Fíjate en patrones como notificaciones que dejan de llegar, brechas en la sincronización donde solo se actualizan algunos registros, campos faltantes o destinos desaparecidos (canales, repos, carpetas), o acciones que funcionan en un espacio de trabajo pero fallan en otro.

La mayoría de los fallos silenciosos provienen de tres raíces:

• Tokens: la clave que demuestra que la integración tiene permiso para actuar.
• Scopes: el acceso específico que la app solicitó, como leer canales o escribir mensajes.
• Modelos de permisos: las reglas de la plataforma y de la organización que deciden lo que realmente está permitido.

Trata el “sin error” como una pista, no como una garantía. Si la interfaz dice “conectado” pero no pasa nada, asume que algo cambió fuera de tu código.

Tokens en lenguaje sencillo: qué expira y qué se revoca

Los problemas con tokens son la causa más común de fallos silenciosos. “Todavía guardado en la base de datos” no significa “todavía válido”.

Un access token es la clave de corto plazo que tu app usa en cada llamada a la API. Muchos proveedores la hacen expirar.

Un refresh token es la tarjeta de renovación a más largo plazo. Tu app lo intercambia por un nuevo access token sin forzar al usuario a iniciar sesión otra vez. Si nunca guardaste un refresh token (o lo perdiste), la integración suele funcionar al principio y luego quedarse en silencio.

Los tokens suelen volverse inválidos por razones previsibles:

• Expiración por tiempo (los access tokens caducan; los refresh tokens también pueden expirar)
• El usuario revoca el acceso
• Un administrador elimina la app, cambia la política de la organización o desactiva la integración
• Eventos de seguridad como reset de contraseña, cambios de SSO o protecciones por inicios de sesión sospechosos
• Rotación de secretos que rompe accidentalmente el intercambio de tokens

Dónde guardas los tokens afecta tanto la seguridad como la fiabilidad. El almacenamiento en cliente (como localStorage) puede borrarse, copiarse o ser bloqueado por políticas del navegador. El almacenamiento en servidor suele ser más seguro, pero solo si se trata como una contraseña: encriptado at rest, acceso muy limitado y nunca impreso en logs.

La rotación de tokens debería sentirse aburrida para los usuarios. Apunta a “solapamiento, luego cambio”: mantén el token antiguo funcionando durante una ventana corta mientras empiezas a usar el nuevo, y ofrece una ruta de re-autenticación clara cuando la renovación falle.

Ejemplo: un bot de alertas de Slack publica bien durante una semana y luego se queda en silencio. El access token expiró y la app nunca guardó un refresh token, por lo que no puede renovarlo. La solución real no es solo “obtener un token nuevo”. Es guardar los tokens de forma segura y manejar las renovaciones (y sus fallos) intencionalmente.

Scopes vs permisos: el desajuste que causa fallos inesperados

Los scopes son lo que una integración solicita. Aparecen en la pantalla de consentimiento OAuth o en la configuración de la app como “Esta app quiere leer mensajes” o “Esta app quiere escribir en issues”.

Los permisos son lo que el usuario u organización pueden hacer realmente. Alguien puede aprobar un scope y la plataforma aún puede bloquear la acción por reglas de la organización, límites de rol o acceso a recursos.

Por eso “la app tiene el scope” aún puede fallar. El token indica que la app tiene permiso para intentarlo, pero el entorno aún puede decir que no.

Ejemplos comunes:

• Slack: tu app tiene chat:write, pero no está en el canal, o la configuración de la organización restringe los posts.
• Google: tienes un scope de Drive, pero la cuenta no puede acceder a una unidad compartida, o un admin bloqueó la app para el dominio.
• GitHub: tu app solicita permisos sobre repositorios, pero las políticas de la organización limitan el acceso de terceros, o la app no está instalada en los repos correctos.

Cuando algo falla, separa “lo que la app solicitó” de “lo que el entorno permite”. Dos preguntas suelen descubrir la brecha:

1. ¿Solicitamos los scopes que necesitamos para la funcionalidad tal como está hoy?
2. ¿Este usuario/organización tiene acceso al workspace, carpeta, repo o canal exacto implicado?

El principio de mínimo privilegio es bueno, pero tiene una trampa: si quitas scopes sin revisar todos los caminos de la funcionalidad, puedes crear fallos silenciosos que solo aparecen en casos límite.

Un hábito práctico es mantener un mapa corto de scopes por función: qué hace, qué scopes necesita y qué reglas de la organización podrían bloquearla.

Haz un inventario de integraciones antes de depurar

Los fallos silenciosos son difíciles de arreglar si no sabes qué está conectado a qué. Antes de cambiar código, crea un inventario simple. Convierte una adivinanza en una lista de verificación.

Lista cada sistema externo que toca tu app, incluso los “pequeños”: Slack, Google, GitHub, proveedores de email, analytics, pagos y cualquier herramienta administrativa interna. Muchos errores misteriosos ocurren porque una integración existe en staging pero no en producción, o porque producción apunta a un workspace/organización diferente al que probaste.

Para cada integración, anota quién la instaló, a qué workspace/organización pertenece y qué se supone que debe hacer. “Alertas de Slack” es demasiado vago. Indica si publica en un canal o varios, lee mensajes, crea canales, gestiona webhooks o sincroniza datos.

También captura el modelo de autenticación, porque tus pasos de auditoría dependen de ello. Las instalaciones OAuth, GitHub Apps, tokens de acceso personal y las cuentas de servicio pueden impulsar funciones similares, pero fallan de maneras distintas.

Una plantilla de inventario de una página:

• Sistema + cuenta (workspace de Slack, proyecto de Google, organización de GitHub)
• Propietario (quién la instaló y quién puede reinstalarla)
• Método de auth (OAuth, GitHub App, PAT, cuenta de servicio)
• Acciones esperadas (publicar mensajes, sincronizar calendario, leer repos)
• Dónde corre (prod, staging, local; además de las variables de entorno usadas)

Ejemplo: un fundador hereda una app donde las notificaciones de Slack a veces se detienen. El inventario muestra que la app de Slack fue instalada por un contratista en un workspace distinto al de producción, así que el token “funcionante” nunca estuvo ligado al canal real.

Paso a paso: una auditoría práctica que puedes repetir

La mayoría de fallos silenciosos son aburridos: una app se desinstaló, un token expiró o alguien cambió las reglas de aprobación. Las auditorías más rápidas siguen la misma pequeña rutina cada vez.

Empieza confirmando que la integración sigue siendo real donde vive:

• La app está instalada
• Está conectada al workspace/organización correcto
• Producción apunta a producción (no a staging) y las variables de entorno coinciden

Luego haz cinco comprobaciones, en orden:

• Existencia y propiedad: ¿Quién la instaló y aún tiene acceso?
• Salud del token: ¿El token está expirado, revocado o sin uso durante semanas (una pista de que no se está llamando)?
• Coincidencia de scopes: Compara lo que la app necesita hoy con lo que se le concedió.
• Modelo de permisos: Confirma que roles de usuario, políticas de la organización, aprobaciones de apps o configuraciones de admin todavía lo permiten.
• Una prueba real de extremo a extremo: Dispara un evento real y verifica el efecto secundario donde debería aparecer.

Cuando compares scopes, no confíes en lo que el código asume. Anota las acciones exactas que la integración debe realizar (publicar un mensaje, leer un archivo, abrir un issue) y asigna cada acción a un scope concedido.

Luego haz que el próximo fallo suene alto. Como mínimo, alertar sobre errores 401/403 repetidos, alertar cuando falla el refresh y alertar cuando un job corre pero produce cero salida.

Auditorías de Slack: scopes, acceso a canales y problemas de quien instaló

Las integraciones de Slack a menudo parecen “sanas” porque la app sigue instalada, pero el bot pierde en silencio la capacidad de leer un canal, publicar un mensaje o obtener datos de usuarios.

Empieza por básicos que se pasan por alto:

• En qué workspace está instalada la app
• Qué entorno (prod vs staging) está usando esa instalación
• Si el token que usas pertenece realmente al workspace esperado

Luego, relaciona las funciones con los scopes OAuth. Publicar alertas suele necesitar chat:write. Buscar usuarios puede requerir users:read. Leer canales y reaccionar a eventos puede requerir scopes de canal. Faltar un solo scope puede convertirse en “no pasa nada” si tu código atrapa errores o los registra en un lugar que nadie revisa.

El acceso a canales es otra trampa común. Publicar en un canal privado no es lo mismo que publicar en uno público. El bot debe ser invitado, y algunos workspaces restringen el acceso de apps a canales privados por completo. Si las alertas se detuvieron en un canal pero siguen funcionando en otro, sospecha de la membresía del canal o de un cambio de política.

Los problemas del instalador también causan fallos silenciosos. Muchas apps de Slack son autorizadas por una sola persona. Si esa persona se va o su rol cambia, la app puede perder acceso según las reglas del workspace.

Un flujo de auditoría simple para Slack:

• Confirma que workspace, app y variables de entorno coinciden con lo que espera producción.
• Comprueba los scopes actuales frente a las acciones exactas que realiza tu app.
• Verifica que el bot es miembro de cada canal objetivo (especialmente los privados).
• Identifica quién autorizó la app y si sigue activo.
• Revisa qué cambió después de la última reinstalación, ya que scopes y permisos pueden modificarse.

Auditorías de Google: consentimiento, refresh tokens y controles admin

Las integraciones de Google a menudo fallan sin errores claros porque el “sí” que obtuviste durante la configuración no siempre es el “sí” que tienes hoy.

Empieza por la pantalla de consentimiento OAuth. Si la app sigue en testing, sin verificar o ligada a un proyecto cuyo dueño cambió, los usuarios pueden perder acceso sin que nadie toque tu código. Verifica que esté publicada para el tipo de usuario correcto (interno vs externo) y que los detalles de la app sigan coincidiendo con lo que Google espera.

Luego céntrate en los refresh tokens. Muchas apps funcionan bien por una hora (la vida del access token) y luego se detienen cuando el refresh token se revoca, caduca por inactividad o es bloqueado por una política. Por eso los desarrolladores ven “funciona en mi máquina”: siguen autorizando de nuevo.

Comprobaciones de alto valor para repetir:

• Estado de la pantalla de consentimiento (publicada, verificación, tipo de usuario)
• Que existan refresh tokens y que la renovación siga funcionando
• Reglas de Google Workspace (control de acceso a apps y consentimiento de usuarios)
• Configuración de cuentas de servicio y delegación a nivel de dominio (si se usa)
• Scopes sensibles, especialmente si la verificación o las políticas cambiaron

Los controles de admin del workspace son una sorpresa común. Un admin puede restringir apps de terceros, bloquear el consentimiento de usuarios o limitar qué client IDs OAuth están permitidos. La integración puede seguir “conectándose” para un usuario pero fallar para todos los demás.

Las cuentas de servicio añaden otra capa: la delegación a nivel de dominio debe estar habilitada, el admin debe aprobar el cliente y los scopes delegados deben coincidir con lo que solicita tu código. Un solo scope faltante puede parecer un error de datos.

Auditorías de GitHub: tipo de app, políticas de la org y deriva de scopes

Las integraciones de GitHub suelen fallar en silencio porque “lo que autentica” no es lo que crees. Primero, nombra el tipo de autenticación:

• Una GitHub App (instalada en una org o repos)
• Una OAuth App (basada en usuario)
• Un personal access token (PAT)

Cada una falla de forma distinta y la solución cambia según el caso.

Qué verificar dentro de una organización de GitHub

Confirma qué puede tocar la integración. Con GitHub Apps, los permisos se dividen en áreas (contents, issues, pull requests, checks, workflows) y pueden ser de solo lectura o lectura/escritura. También comprueba si la app está instalada en todos los repos o solo en repos específicos. Un fallo silencioso común es añadir un repo nuevo mientras la app sigue teniendo acceso solo a la lista antigua de repos.

Luego busca controles de la org que bloqueen el acceso sin errores evidentes. Muchas organizaciones aplican SAML SSO. En ese caso, los tokens de usuario pueden necesitar autorización SSO explícita y las automatizaciones pueden detenerse cuando el propietario del token se va. Otro bloqueo son las reglas de la organización que requieren aprobación admin para instalaciones de apps o nuevas solicitudes de permisos.

Atento a la deriva de scopes: el código empieza a usar una nueva API (por ejemplo, crear checks o publicar comentarios en PRs), pero la app sigue con el conjunto de permisos antiguo y menor. Las llamadas fallan, se reintentan y desaparecen en los logs.

Una auditoría rápida de GitHub:

• Identifica el tipo de auth y quién lo posee (cuenta de servicio vs empleado real).
• Confirma que los permisos actuales coinciden con lo que la integración realmente hace.
• Verifica la cobertura de instalación (qué orgs y repos están incluidos).
• Revisa las políticas de la org: enforcement de SSO, reglas de aprobación de apps, restricciones.
• Revisa “arreglos rápidos” recientes donde alguien intercambió tokens durante una migración.

Ejemplo: el bot de alertas de Slack que deja de publicar en silencio

Un fallo silencioso común se ve así: tu producto publica una alerta en Slack cada vez que falla un job en segundo plano. Todos se acostumbran, así que nadie revisa el dashboard tan a menudo.

Entonces, una semana, los jobs siguen fallando, pero Slack está en silencio. El problema no son los jobs. Es la integración.

Un patrón frecuente: la persona que instaló la app de Slack (a menudo un contratista o un miembro inicial del equipo) se marcha. Después, su cuenta se desactiva o la app se elimina durante una limpieza del workspace. Slack revoca el token, pero tu app sigue corriendo y sigue intentando publicar. Si tu código solo registra el error en un log del servidor (o lo atrapa), nadie ve la ruptura.

Un camino de auditoría simple suele encontrarlo rápido:

• Verifica que la app esté instalada en el workspace correcto de Slack.
• Confirma quién la instaló (y si esa cuenta sigue existiendo).
• Comprueba los scopes frente a lo que intentas hacer.
• Valida el acceso al canal: ¿está el bot en el canal y es el canal privado?
• Envía una alerta de prueba ahora y observa la petición/respuesta completa.

La solución suele ser directa: reautorizar con un propietario estable (no una cuenta personal que pueda desaparecer), confirmar que los scopes de Slack coinciden con tus acciones reales y re-invitar el bot a los canales objetivo.

Para evitar que se repita, añade un heartbeat ligero (como un mensaje de prueba diario a un canal de baja actividad) más monitorización que te alerte cuando Slack devuelva un error de autenticación o permiso.

Errores comunes que mantienen los fallos ocultos

Los fallos silenciosos suelen ocurrir porque una integración parece bien en la superficie. La petición devuelve algo que parece OK, pero el efecto secundario (publicar un mensaje, crear un archivo, abrir un PR) nunca ocurre.

Una trampa es tratar una respuesta 200 como prueba de que el job funcionó. Algunas APIs devuelven éxito por trabajo aceptado y fallan después (limites de tasa, falta de acceso a canal, bloqueos por políticas). Si no verificas el efecto secundario, puedes perder el fallo durante días.

Otro error es capturar excepciones y esconderlas. Los equipos suelen loguear la excepción y continuar, así que los usuarios ven “todo está bien” mientras la integración está rota. Si un paso de integración es requerido (pagos, notificaciones, despliegues), los errores deben alertar a una persona real.

Los scopes y el consentimiento también son fáciles de malinterpretar. Puedes solicitar nuevos scopes de Slack o permisos OAuth de Google en el código, pero nada cambia hasta que la app se reinstala o el usuario vuelve a consentir. Eso crea un desajuste: tu código asume nuevo acceso, pero los tokens de producción aún no lo tienen.

Mezclar permisos de usuario con permisos de app genera bugs de “funciona en mi cuenta”. El token de usuario de un desarrollador puede acceder a un canal privado de Slack o a un repo de GitHub, mientras que la instalación real de la app no puede.

Las decisiones sobre almacenamiento de tokens pueden ocultar problemas y crear riesgos:

• Los tokens guardados en el cliente se borran sin registro.
• Los tokens filtran en logs, haciendo el debugging más difícil.
• Los tokens se comparten entre entornos, de modo que cambios en staging rompen producción.

Lista rápida y siguientes pasos

Los fallos silenciosos suelen reducirse a una de tres cosas: la app ya no está instalada o aprobada, el token dejó de funcionar, o la integración solicita el acceso equivocado para lo que intenta hacer.

Antes de cambiar código, haz un repaso rápido de lo básico:

• Confirma que la integración sigue apareciendo como instalada y aprobada en el workspace/organización, y que está conectada a la cuenta que esperas.
• Dispara una re-auth o un refresh de token normal (sin atajos). Si no puede re-autenticarse, trátalo como un problema de acceso, no como un bug de código.
• Compara scopes/permissions concedidos con lo que la funcionalidad necesita hoy, no con lo que necesitaba cuando la construiste.
• Revisa cambios de política: enforcement de SSO, reglas de aprobación de apps, repos restringidos, requisitos de consentimiento admin.
• Busca manejo silencioso de errores: bloques catch vacíos, respuestas no-200 ignoradas, reintentos que nunca alertan o logs faltantes para fallos de auth.

Luego escribe el acceso mínimo que la integración necesita: scopes, recursos (canales, drives, repos) y quién debe instalarla (usuario vs admin). Programa una mini-auditoría mensual: una acción real de prueba por integración y un lugar para revisar fallos.

Si heredaste una app generada por IA donde las integraciones son inestables o inseguras, FixMyMess (fixmymess.ai) puede hacer una auditoría de código gratuita para localizar el manejo de tokens, las brechas de scopes y los casos límite de permisos, y luego repararlos para que los fallos sean visibles y la recuperación predecible.