Conectores e integraciones

Cómo funcionan los conectores

Cada conector declara un flujo de conexión (connectFlow) que determina cómo se obtienen las credenciales. Hay tres tipos:

• oauth — el usuario autoriza el acceso desde la pantalla de login del propio proveedor. SHARA nunca ve la contraseña; recibe un token de acceso (y, cuando aplica, uno de refresco) con los permisos que el usuario consintió.
• api-key — pegas una clave generada en el panel del servicio. La clave se cifra antes de persistirse y se asocia únicamente a tu tenant.
• webhook — SHARA provisiona un endpoint y un secreto por tenant para recibir eventos entrantes de sistemas externos. El secreto nunca se comparte entre tenants.

Una vez conectado, el agente que necesite la herramienta detecta la integración activa y la añade a sus capacidades automáticamente. Cada conector publica un conjunto de tools nativas (acciones concretas como «enviar correo» o «crear evento») que los agentes pueden invocar.

Catálogo de conectores OAuth

Conectores que se autentican mediante OAuth (consentimiento del usuario en el proveedor). La columna Tools nativas indica las acciones que el conector expone a los agentes.

Catálogo de conectores con API key o webhook

Conectores que no usan OAuth. La clave o el secreto es siempre por tenant y se cifra con el mismo almacén seguro que los tokens OAuth.

Conectores universales

Además del catálogo, todos los planes desde First disponen de mecanismos para conectar sistemas que no tienen un conector específico:

• Desktop Agent — app instalable para Windows, macOS y Linux que expone tus apps locales (hoja de cálculo, contabilidad, ERP propietario) como herramientas del equipo.
• Server Agent — agente residente en tu servidor para exponer servicios internos a los agentes.
• HTTP webhooks — recibe eventos de cualquier sistema y dispara flujos en SHARA.
• MCP gateway — protocolo Model Context Protocol para integraciones bidireccionales con tus propias herramientas.

Las acciones del Desktop Agent y del Server Agent fuera de la allowlist requieren aprobación humana antes de ejecutarse. Lee Seguridad.

Tabla de permisos OAuth por conector

La columna Preset por defecto es el conjunto de scopes que SHARA solicita cuando no especificas ninguno al iniciar la conexión. Puedes pedir un subconjunto del preset para ajustarte al mínimo privilegio: cualquier scope fuera del catálogo declarado se rechaza con 400 unknown_scopes, y una lista vacía con 400 empty_scopes.

Google — Gmail, Calendar, Drive

Los scopes de Gmail, Calendar y Drive son sensibles: el proveedor exige superar su proceso de verificación de la app antes de habilitarlos para cuentas externas. El scope drive.file (acceso solo a archivos creados por la app) es la opción menos invasiva para Drive.

Microsoft 365 / Entra ID — Outlook, Calendar, Teams, OneDrive

Todos los flujos de Microsoft añaden siempre offline_access (para emitir token de refresco) y User.Read (identidad básica). El refresco de token rota el token de refresco en cada renovación; SHARA lo contempla de forma transparente.

Algunos scopes de Microsoft (por ejemplo Files.ReadWrite.All) pueden requerir el consentimiento del administrador global del tenant del cliente. Esto está previsto en el onboarding empresarial.

Slack — token de bot y token de usuario

Slack distingue entre el token de bot (xoxb, el modo por defecto) y el token de usuario (xoxp, opcional). Por defecto SHARA usa el token de bot; el de usuario solo se activa si necesitas búsqueda de mensajes.

CRM — HubSpot y Pipedrive

Los CRM usan scopes por objeto/recurso. Concede permiso de escritura solo en los objetos donde el agente vaya a crear o actualizar registros (por ejemplo, solo deals si únicamente gestiona oportunidades).

Otros conectores OAuth

Flujo de conexión paso a paso

Para un cliente o desarrollador externo, el contrato público de integración se compone de dos endpoints principales y el callback del proveedor. El recorrido completo es:

1. 1 El cliente consulta el catálogo y el estado de conexión: GET /v1/integrations devuelve cada conector con su connectFlow y si ya está conectado para tu tenant.
2. 2 El cliente inicia la conexión: POST /v1/integrations/:slug/connect. Según el connectFlow, para oauth devuelve { authUrl, state }; para api-key recibe la clave y la cifra; para webhook provisiona el token por tenant.
3. 3 El usuario abre authUrl y autoriza en el proveedor. Tras consentir, el proveedor redirige al callback público de SHARA con un code y el state.
4. 4 SHARA valida el state, intercambia el code por los tokens, los cifra y los persiste asociados a tu tenant. La integración pasa a estado conectado.
5. 5 A partir de ahí, los agentes que necesiten ese conector lo usan automáticamente. Los tokens nunca se devuelven al cliente.

El catálogo y el estado de conexión se consultan así:

# Listar el catálogo de conectores y su estado para tu tenant
curl -s https://api.aiginer.com/v1/integrations \
  -H "Authorization: Bearer $SHARA_TOKEN"

La respuesta describe cada conector y su disponibilidad:

{
  "integrations": [
    {
      "slug": "gmail",
      "name": "Gmail",
      "category": "communication",
      "connectFlow": "oauth",
      "connected": false,
      "scopes": ["gmail.readonly", "gmail.send", "gmail.modify", "userinfo.email"]
    },
    {
      "slug": "resend",
      "name": "Resend",
      "category": "productivity",
      "connectFlow": "api-key",
      "connected": true
    }
  ]
}

Para iniciar una conexión OAuth pidiendo un subconjunto de scopes (mínimo privilegio):

# Conectar Gmail solo en modo lectura (subconjunto del preset)
curl -s -X POST https://api.aiginer.com/v1/integrations/gmail/connect \
  -H "Authorization: Bearer $SHARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["gmail.readonly", "userinfo.email"] }'

La respuesta para un flujo oauth devuelve la URL de autorización y el state de un solo uso:

{
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&state=...",
  "state": "9f3c1a7e-...-single-use",
  "expiresIn": 600
}

Para conectores api-key, el mismo endpoint recibe la clave en el cuerpo y la cifra antes de persistirla:

# Conectar un servicio de tipo api-key
curl -s -X POST https://api.aiginer.com/v1/integrations/resend/connect \
  -H "Authorization: Bearer $SHARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "re_live_..." }'

Garantías de seguridad del flujo OAuth

El flujo de conexión incorpora varias protecciones por diseño, aplicadas de forma uniforme a todos los proveedores:

• PKCE en todos los proveedores. Cada conexión genera un code_verifier y su code_challenge, incluso para clientes confidenciales. Esto protege el intercambio de código frente a interceptación.
• state de un solo uso (delete-on-read). El state se elimina del almacén en el instante en que se lee, antes de validar su caducidad. Reutilizar el mismo state falla con 400 state_mismatch. TTL de 10 minutos.
• Autoridad ligada al token. El inicio de la conexión exige un JWT autenticado; la identidad y el tenantId se derivan del token, nunca de la query ni del body. El callback no necesita JWT: su autoridad es el state validado, atado al tenant en el arranque.
• Tokens cifrados antes de persistir. Los tokens de acceso y de refresco se cifran con cifrado autenticado en un almacén seguro, con el material criptográfico aislado por tenant, y nunca se devuelven al cliente.
• Validación de scopes contra el manifest. Los scopes solicitados deben ser un subconjunto de los declarados; en caso contrario, 400 unknown_scopes (o 400 empty_scopes si la lista está vacía).
• Errores del proveedor redactados. Los mensajes de error del SDK del proveedor se redactan antes de registrarse o devolverse, para no filtrar datos sensibles.
• Refresco automático. Un proceso periódico renueva los tokens próximos a expirar. Si el proveedor revoca el acceso, la integración pasa a estado revoked y deja de utilizarse hasta que se reconecte.

Buenas prácticas de configuración

• Pide el mínimo scope necesario. El preset por defecto es amplio por comodidad. Si tu caso de uso es solo lectura, solicita el subconjunto (por ejemplo gmail.readonly sin gmail.send, o Calendars.Read en lugar de Calendars.ReadWrite). Menos scope = menor superficie y menos fricción de verificación.
• Registra el redirect_uri exacto en la consola del proveedor: debe coincidir carácter a carácter con el callback público de la API.
• Google: los scopes de Gmail, Calendar y Drive son sensibles; prepara la verificación de la app antes de exponerlos a cuentas externas.
• Microsoft: algunos scopes exigen consentimiento del administrador global del tenant del cliente. El token de refresco rota en cada renovación.
• Slack: usa el token de bot por defecto; activa el token de usuario solo si necesitas search:read.
• CRM (HubSpot / Pipedrive): concede escritura únicamente en los objetos que el agente vaya a modificar.
• API key y webhook: la clave o el secreto es siempre por tenant, nunca compartido, y se cifra con el mismo almacén seguro que los tokens OAuth.

¿Falta tu herramienta?

Si usas un sistema que aún no tiene conector nativo, casi siempre se puede integrar vía webhooks, MCP gateway o el Server Agent. Cuéntanos tu caso en integraciones@aiginer.com y valoramos añadirlo.