Subcuentas delegadas sin exponer claves: patrón seguro para agencias

El problema: autonomía del cliente sin perder control

Una agencia que gestiona entregables para varios clientes suele necesitar dos cosas que parecen opuestas: que cada cliente pueda consultar, revisar, subir o descargar archivos con cierta autonomía, y que las operaciones privilegiadas sigan bajo control técnico de la agencia. El riesgo aparece cuando se intenta resolver rápido compartiendo credenciales, creando un usuario genérico para todos o dejando que el navegador invoque acciones internas con una clave API. Ese camino puede mezclar espacios, romper la trazabilidad y hacer muy difícil revocar accesos sin afectar a otros clientes.

El objetivo correcto no es esconder una interfaz, sino separar responsabilidades. El cliente debe ver solo su contexto autorizado; el backend de la agencia debe ejecutar las acciones con privilegios; y Apification Cloud debe aplicar permisos, visibilidad, grupos, restricciones y sesiones embebidas limitadas. Este patrón permite delegar subcuentas sin exponer claves API, manteniendo los secretos en servidor y reduciendo la dependencia de operaciones manuales como mover archivos, generar enlaces o comprobar trabajos de transformación uno por uno.

• Evita entregar credenciales API al cliente o incluirlas en JavaScript.
• No uses una cuenta compartida para varios clientes si necesitas aislamiento operativo.
• Define desde el inicio qué acciones son de usuario y cuáles son de backend.
• Trata cada exposición de contenido como una excepción explícita sobre recursos privados por defecto.

Modelo mental: tres capas separadas

La primera capa es la interfaz embebida. Apification permite integrar Cloud mediante iframe, configuración heredada y temas visuales, de modo que una agencia o reseller pueda ofrecer una experiencia integrada en su propio ecosistema. En este modelo, la sesión del iframe debe construirse antes de mostrarlo: identidad, política efectiva y configuración visual se resuelven en el servidor para cada lanzamiento. La sesión embebida puede limitarse a la subcuenta, usuario y recursos permitidos, lo que evita que el navegador decida por sí mismo qué puede abrir.

La segunda capa es el backend propio. Ahí viven las credenciales API, secretos webhook y material de firma, porque Apification especifica que deben permanecer en servidor y que el navegador solo debe recibir contexto limitado o temporal. La tercera capa son los controles de Cloud: permisos, usuarios, grupos, visibilidad, restricciones, OTP, autenticación externa cuando corresponda y ventanas de publicación. La regla de diseño es sencilla: la interfaz guía al usuario, el backend ejecuta acciones privilegiadas y Cloud conserva la política de acceso asociada al recurso.

• Iframe: experiencia de usuario y selección dentro de un contexto limitado.
• Backend: creación de sesiones firmadas, llamadas API y validación de reglas del cliente.
• Cloud: archivos, carpetas, servicios editables, resultados, historial, permisos y visibilidad.
• Webhooks: notificaciones de eventos con firma, reintentos, historial y estadísticas.

Qué aporta Apification a este patrón

Apification reúne las piezas necesarias para una delegación controlada. Cloud conserva archivos, carpetas, servicios editables y resultados generados dentro de un mismo espacio de trabajo organizado y versionado. Los recursos nuevos son privados por defecto y solo se publican o comparten cuando se configura expresamente su visibilidad o sus destinatarios. Además, pueden compartirse con usuarios o grupos sin cambiar la visibilidad pública, algo importante cuando una agencia necesita dar acceso interno a revisores del cliente sin convertir un entregable en público.

Para la integración, Apification ofrece REST API servidor a servidor para gestionar recursos Cloud, usuarios, configuración y trabajos de transformación desde el backend, además de un contrato OpenAPI descargable con esquemas de petición y respuesta. También permite integrar Cloud y servicios mediante iframe, API, webhooks y JavaScript, pero la clave es no confundir “integración con JavaScript” con “secretos en el navegador”. Para operaciones asincrónicas, los webhooks firmados con reintentos, historial y estadísticas son preferibles al polling en producción cuando se esperan eventos de transformación completada o fallida.

• Usa claves API específicas y con solo los scopes necesarios.
• Apóyate en OpenAPI para validar contratos antes de programar.
• Utiliza webhooks en producción para reducir consultas repetitivas y mejorar trazabilidad.
• Reserva OTP para interacciones públicas; usa usuarios, grupos y visibilidad para acceso interno.

Arquitectura recomendada para subcuentas delegadas

El flujo recomendado empieza en el portal de la agencia. El usuario del cliente se autentica en el sistema de la agencia y solicita abrir su área de archivos o una operación concreta. El backend valida a qué cliente pertenece, qué rol tiene y qué recursos puede usar. Solo entonces solicita una sesión iframe firmada y de corta duración desde el backend de confianza, con el contexto de cliente aislado: subcuenta, usuario y recursos permitidos. El navegador recibe esa sesión limitada, no una clave API ni un secreto reutilizable.

Cuando el cliente necesita una acción privilegiada, como crear un trabajo de transformación, consultar un recurso o preparar una descarga transformada, el navegador debe llamar al backend de la agencia, no directamente con credenciales permanentes. El backend aplica reglas de negocio, invoca la API REST de Apification con autenticación Bearer desde servidor y registra la acción. Si el host y el iframe se coordinan mediante mensajes del navegador, esos mensajes deben validarse: el receptor debe comprobar origen, intención y datos esperados, siguiendo el principio general de validación de comunicaciones entre ventanas.

• Paso 1: autentica al cliente en el portal de la agencia.
• Paso 2: resuelve en servidor identidad, política efectiva y tema visual.
• Paso 3: solicita una sesión iframe firmada, limitada y de corta duración.
• Paso 4: ejecuta llamadas REST solo desde backend con clave de scopes mínimos.
• Paso 5: registra eventos y respuestas para auditoría operativa.

Delegación por cliente: permisos, espacios y reglas

La separación no debe depender únicamente del nombre de una carpeta. En Apification, mover un elemento Cloud modifica su organización, no su identidad: sus propiedades y reglas de acceso continúan asociadas al mismo elemento. Esto es útil para reordenar entregables sin perder controles, pero también demuestra por qué el aislamiento debe basarse en permisos, usuarios, grupos, visibilidad y recursos autorizados, no en convenciones frágiles como “todo lo que esté bajo /cliente-a”. La agencia debe documentar la matriz de acceso por cliente y revisarla cuando cambie el contrato de servicio.

Una matriz práctica distingue al menos cinco acciones: subir o incorporar archivos, transformar o procesar contenido, revisar versiones, descargar originales o formatos generados, y publicar enlaces o accesos. Cloud permite descargar el archivo fuente o generar un formato compatible desde el flujo de compartir, por lo que conviene decidir quién puede entregar originales y quién solo debe recibir derivados. Si se usan servicios editables, como documentos de oficina, edición de imágenes o editores multimedia, la misma lógica aplica: el cliente no necesita permiso universal, sino el mínimo conjunto de acciones para su caso.

• Define grupos por cliente o por rol dentro del cliente.
• Separa revisión, transformación, descarga y publicación como permisos distintos en tu diseño.
• Evita que un cambio de carpeta sea el único mecanismo de control.
• Mantén un procedimiento de revocación cuando un contacto del cliente deja de participar.

Operaciones típicas y cómo automatizarlas

En una operación diaria, el cliente puede seleccionar archivos desde el iframe, revisar entregables en Cloud, descargar un original o pedir una versión transformada. La agencia, por su parte, puede crear trabajos desde el backend, aplicar reglas del cliente y usar el historial de los elementos para revisar versiones anteriores o restaurar contenido cuando sea necesario. Este enfoque reduce correos sueltos y evita que el equipo interno tenga que actuar como intermediario para cada descarga o revisión básica.

Para procesos asincrónicos, diseña alrededor de eventos. Si una transformación se completa o falla, un webhook firmado puede avisar al backend de la agencia. Ese backend debe verificar la firma con el secreto guardado en servidor, deduplicar eventos y actualizar su propio estado. Apification soporta escrituras idempotentes mediante una clave de idempotencia en operaciones compatibles, por lo que las acciones que podrían repetirse por reintentos, doble clic o reconexiones deben enviar una clave estable. Así evitas crear trabajos duplicados o publicar dos veces el mismo resultado.

• Usa webhooks para cierre de trabajos y errores, no solo consultas periódicas.
• Verifica la firma antes de confiar en el contenido del evento.
• Guarda identificadores de eventos o resultados para deduplicar.
• Aplica claves de idempotencia en escrituras compatibles que puedan repetirse.
• Conserva un registro operativo de quién solicitó, qué recurso afectó y cuál fue el resultado.

Errores frecuentes y modos de fallo

El error más grave es poner claves en JavaScript. Aunque una interfaz sea privada o esté detrás de login, cualquier secreto entregado al navegador debe considerarse expuesto. Otro fallo común es usar un único usuario para todos los clientes: puede parecer cómodo al inicio, pero impide atribuir acciones, dificulta revocar accesos y aumenta el impacto de cualquier error de configuración. También es peligroso confiar solo en nombres de carpeta, porque la organización visual no sustituye a reglas de acceso asociadas a recursos y usuarios.

En automatización, los fallos suelen aparecer por no verificar firmas webhook, procesar dos veces el mismo evento o asumir que una importación puntual equivale a sincronización continua. Si una entrega webhook se reintenta y tu backend no es idempotente, puedes duplicar trabajos o notificaciones. Si no pruebas con usuarios de menor privilegio, puedes descubrir tarde que un rol puede descargar originales cuando solo debía ver transformados. La defensa es probar los casos negativos: usuario equivocado, recurso de otro cliente, sesión caducada, firma inválida y repetición de evento.

• No expongas Bearer tokens, secretos webhook ni material de firma en el frontend.
• No mezcles clientes bajo una identidad operativa única.
• No proceses webhooks sin verificar firma y deduplicar.
• No trates una importación puntual desde proveedores externos como sincronización continua.
• No concedas scopes API amplios si la integración solo necesita una parte.

Checklist de implementación antes de producción

Antes de abrir el acceso a clientes, prepara una checklist técnica y otra operativa. En la técnica, crea una clave API específica para la integración y concede únicamente los scopes necesarios de cuenta, Cloud, transformaciones, usuarios o webhooks. Guarda la clave y los secretos en variables o almacenamiento de servidor, nunca en el cliente. Implementa validación de cliente en cada endpoint interno: ninguna petición del navegador debe poder indicar libremente otro cliente, subcuenta o recurso sin que el backend lo compruebe contra su propia autorización.

En la checklist operativa, documenta quién puede subir, transformar, revisar, descargar, compartir y revocar. Crea pruebas con usuarios de menor privilegio, valida sesiones iframe caducadas y revisa que los recursos sigan siendo privados salvo publicación expresa. Para webhooks, prueba firma inválida, evento duplicado y reintento. Para escrituras, aplica idempotencia cuando esté disponible. Por último, define cómo retirar acceso a un cliente o usuario sin afectar a otros: esa capacidad de revocación es una de las razones principales para separar subcuentas y no depender de credenciales compartidas.

• Matriz de permisos por cliente, rol y acción.
• Claves API específicas, scopes mínimos y secretos solo en servidor.
• Sesión iframe firmada, corta y creada desde backend de confianza.
• Validación de subcuenta, usuario y recurso en cada operación.
• Verificación de firmas webhook, deduplicación e idempotencia.
• Pruebas negativas con roles limitados y recursos de otros clientes.
• Plan documentado de revocación de usuarios, grupos y accesos publicados.

Preguntas frecuentes