Conectores e integraciones

Los conectores permiten que tus agentes lean y escriban en tus herramientas reales (correo, calendario, almacenamiento, chat y CRM) mediante OAuth o API key. El flujo de conexión, el cifrado por tenant y los endpoints son idénticos en todos los planes desde First. Las únicas excepciones son HubSpot, Pipedrive y Salesforce, exclusivos de Pro en adelante. El resto del diferencial entre planes está en los agentes departamentales, el orquestador Amadeus, la cuota STU y el soporte.

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.

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 los nombres de las tools que el conector expone a los agentes; Se conecta con indica la ruta que realmente inicia la conexión y Ámbito, quién la conecta.

Empresa o «Mis cuentas». El correo, el calendario y los archivos de cada persona (Google: Gmail, Calendar y Drive; Microsoft: Outlook, Calendar y OneDrive) se conectan en el perfil, en Mis cuentas, y los agentes usan la cuenta de quien les pide algo. Slack y Teams se conectan como empresa y también como cuenta personal. GitHub es personal. El resto de conectores los conecta la empresa una vez, para todo el equipo.

Conector	Slug	Categoría	Tools nativas	Se conecta con	Ámbito
Gmail	me-gmail	Comunicación	send_email, list_inbox, search_mail	POST /me/personal-integrations/:slug/connect	Personal («Mis cuentas»)
Google Calendar	me-google-calendar	Productividad	create_event, list_events, check_availability	POST /me/personal-integrations/:slug/connect	Personal («Mis cuentas»)
Google Drive	me-google-drive	Almacenamiento	list_files, upload_file, download_file	POST /me/personal-integrations/:slug/connect	Personal («Mis cuentas»)
Outlook Mail	me-outlook	Comunicación	send_mail, list_inbox	POST /me/personal-integrations/:slug/connect	Personal («Mis cuentas»)
Microsoft Calendar	me-outlook-calendar	Productividad	create_event, list_events	POST /me/personal-integrations/:slug/connect	Personal («Mis cuentas»)
Microsoft Teams	microsoft-teams	Comunicación	send_message, list_channels, list_chats, search_messages	POST /mcp/oauth/start · POST /me/personal-integrations/:slug/connect	Empresa y personal
OneDrive	me-onedrive	Almacenamiento	list_files, download_file	POST /me/personal-integrations/:slug/connect	Personal («Mis cuentas»)
Slack	slack	Comunicación	send_message, list_channels, search_messages	POST /mcp/oauth/start · POST /me/personal-integrations/:slug/connect	Empresa y personal
GitHub	me-github	Desarrollo	repositorios, incidencias y pull requests	POST /me/personal-integrations/:slug/connect	Personal («Mis cuentas»)
HubSpot (Pro en adelante)	hubspot	CRM y ventas	sync_to_hubspot, fetch_hubspot_deal, import_hubspot_contacts	GET /v1/oauth/hubspot/start	Empresa
Pipedrive (Pro en adelante)	pipedrive	CRM y ventas	sync_to_pipedrive, fetch_pipedrive_deal, import_pipedrive_contacts	GET /v1/oauth/pipedrive/start	Empresa
Notion	notion	Productividad	notion_query_database, notion_create_page, notion_append_block	POST /v1/integrations/notion/connect	Empresa
Calendly	calendly	Productividad	calendly_list_event_types, calendly_list_scheduled_events, calendly_create_invitation	POST /v1/integrations/calendly/connect	Empresa
Dropbox	dropbox	Almacenamiento	dropbox_list_files, dropbox_download_file, dropbox_upload_file	POST /v1/integrations/dropbox/connect	Empresa
Salesforce (Pro en adelante; próximamente)	salesforce	CRM y ventas	importación de contactos y empresas; herramientas de CRM	GET /v1/oauth/salesforce/start?slug=salesforce	Empresa
Confluence	confluence	Documentación	read:pages, write:pages (páginas)	GET /v1/oauth/confluence/start	Empresa
Holded	(ninguno)	CRM y ERP	create_client_in_holded, issue_invoice, send_invoice, sync_stripe_customer_to_holded, fetch_invoice	API key: POST /integrations/holded/connect (sin OAuth)	Empresa

POST /mcp/oauth/start solo atiende los conectores de Google, Microsoft y Slack; cualquier otro nombre del catálogo responde 501 provider_not_configured. Calendly y Dropbox solo arrancan si las credenciales del proveedor están configuradas en la API; si no, el inicio falla con unknown_provider.

Este catálogo crece. Mientras tanto, un sistema sin conector dedicado ya se puede integrar con el MCP gateway, el Server Agent o el Desktop Agent (más abajo).

Catálogo de conectores con API key

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.

Conector	Slug	Flujo	Categoría
Resend	resend	api-key	Email transaccional
Mixpanel	mixpanel	api-key	Analítica
Segment	segment	api-key	Analítica
Coda	coda	api-key (token de API de la cuenta)	Documentación
Zapier	zapier	webhook saliente: se pega la URL «Catch Hook» de tu Zap (solo hooks.zapier.com)	Automatización

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.
• 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 Qué es Shara.

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. En los conectores que atiende POST /mcp/oauth/start (Microsoft Teams y Slack), los Scopes disponibles son ese mismo conjunto: puedes pedir un subconjunto para ajustarte al mínimo privilegio, y cualquier scope fuera de los que declara el conector se rechaza con 400 unknown_scopes, y una lista vacía con 400 empty_scopes. Cuando un servicio también se conecta por persona (cuentas personales, POST /me/personal-integrations/:slug/connect), la tabla lo indica.

Google: Gmail, Calendar, Drive

Solo como cuenta personal (Perfil → Mis cuentas): cada persona conecta su Google y los agentes usan la cuenta de quien les pide algo. Cuentas personales (POST /me/personal-integrations/:slug/connect, con scopes opcional en el cuerpo para sustituir el preset):

Servicio	Slug	Preset por defecto
Gmail	me-gmail	https://www.googleapis.com/auth/gmail.readonly + https://www.googleapis.com/auth/gmail.compose + https://www.googleapis.com/auth/gmail.send + https://www.googleapis.com/auth/userinfo.email
Google Calendar	me-google-calendar	https://www.googleapis.com/auth/calendar.readonly + https://www.googleapis.com/auth/calendar.events + https://www.googleapis.com/auth/userinfo.email
Google Drive	me-google-drive	https://www.googleapis.com/auth/drive + https://www.googleapis.com/auth/userinfo.email

userinfo.email se pide en las conexiones personales para identificar qué cuenta se conectó. Google pide estos permisos en su propia pantalla de consentimiento; que un scope exija verificación de la app antes de habilitarse para cuentas externas lo decide Google.

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

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

Conexión de empresa (POST /mcp/oauth/start), solo Teams: el correo, el calendario y los archivos de cada persona van en Mis cuentas.

Servicio	Preset por defecto	Scopes disponibles
Microsoft Teams	Chat.ReadWrite + ChannelMessage.Send + Channel.ReadBasic.All + Team.ReadBasic.All + offline_access + User.Read	los mismos seis

Cuentas personales (POST /me/personal-integrations/:slug/connect):

Servicio	Slug	Preset por defecto
Outlook	me-outlook	Mail.Send + Mail.ReadWrite + offline_access + openid + User.Read
Outlook Calendar	me-outlook-calendar	Calendars.ReadWrite + offline_access + openid + User.Read
Microsoft Teams	me-teams	Chat.ReadWrite + ChannelMessage.Send + Team.ReadBasic.All + offline_access + openid + User.Read
OneDrive	me-onedrive	Files.ReadWrite + offline_access + openid + User.Read

Que un scope de Microsoft requiera el consentimiento del administrador del tenant del cliente depende de la configuración de Microsoft Entra de ese tenant, no de Shara.

Slack

Conexión de empresa (POST /mcp/oauth/start). Shara pide scopes de bot y, además, un ámbito de usuario (search:read) para poder buscar mensajes: Slack no deja buscar con el token del bot. Las conexiones hechas antes de añadirlo piden reconectar para poder buscar.

Tipo	Preset por defecto	Scopes disponibles
Bot	chat:write + channels:read + users:read	los mismos tres
Usuario	search:read	el mismo

Cuenta personal (me-slack, POST /me/personal-integrations/:slug/connect): chat:write + channels:history + im:history + identity.basic + identity.email.

GitHub

Solo como cuenta personal (me-github, Perfil → Mis cuentas). Scopes: read:user + user:email + repo (GitHub no tiene un scope de solo lectura para repositorios privados). Los agentes leen repositorios, incidencias y pull requests con la cuenta de quien les pide algo.

CRM y ERP: HubSpot, Pipedrive, Salesforce y Holded

HubSpot, Pipedrive y Salesforce son exclusivos de Pro en adelante. Cada uno tiene su propia ruta de inicio, que no admite parámetro de scopes: pide siempre el preset de abajo.

CRM / ERP	Ruta	Scopes solicitados
HubSpot	GET /v1/oauth/hubspot/start	oauth + crm.objects.contacts.read + crm.objects.contacts.write + crm.objects.deals.read + crm.objects.deals.write + crm.objects.companies.read + crm.objects.companies.write + crm.schemas.deals.read
Pipedrive	GET /v1/oauth/pipedrive/start	base + deals:full + contacts:full + search:read + users:read
Salesforce	GET /v1/oauth/salesforce/start?slug=salesforce	api + refresh_token
Holded	POST /integrations/holded/connect	Sin scopes: API key por tenant, validada contra Holded y cifrada por tenant como el resto de credenciales.

Otros conectores OAuth

Se conectan con POST /v1/integrations/:slug/connect, que usa estos scopes salvo que el cuerpo envíe sus propios scopes.

Conector	Preset por defecto	Notas de scopes
Notion	(vacío)	No usa scopes; el usuario elige workspace y páginas en su propio consentimiento.
Calendly	default
Dropbox	files.metadata.read + files.content.read + files.content.write + account_info.read

El catálogo de conectores crece. Si el sistema que usas aún no aparece, el MCP gateway, el Server Agent o el Desktop Agent pueden conectarlo hasta que tenga su conector dedicado.

Flujo de conexión paso a paso

Para un cliente o desarrollador externo, el contrato público de integración se compone de la consulta de estado, un endpoint para iniciar la conexión y el callback del proveedor. Todos exigen la sesión de un administrador con la sesión iniciada (Authorization: Bearer <token de sesión>); no aceptan API key. El recorrido completo es:

1. El cliente consulta el estado: GET /v1/integrations devuelve cada conector que sirve ese endpoint con su connectFlow, su status (disconnected, connected, error o refreshing) y los scopesGranted de tu tenant.
2. El cliente inicia la conexión. Hay dos rutas según el conector:
   • Conectores de Google, Microsoft y Slack del catálogo MCP (por ejemplo gmail, outlook-mail, slack): POST /mcp/oauth/start con { "mcpServerName": "<nombre>", "scopes": [...] } (scopes es opcional) devuelve { authUrl, state }.
   • Conectores que sirve /v1/integrations (por ejemplo notion, resend; HubSpot y Holded usan rutas propias, ver las tablas de arriba): POST /v1/integrations/:slug/connect. Según el connectFlow, para oauth devuelve { kind: "oauth", authUrl, state }; para api-key recibe la clave, la cifra y devuelve { kind: "connected", integration }.
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. 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. A partir de ahí, los agentes que necesiten ese conector lo usan automáticamente. Los tokens nunca se devuelven al cliente.

El estado de los conectores se consulta así:

# Listar los conectores que sirve /v1/integrations y su estado para tu tenant
curl -s https://api.sharasaas.com/v1/integrations \
  -H "Authorization: Bearer $SHARA_SESSION_TOKEN"

La respuesta describe cada conector y su estado:

{
  "integrations": [
    {
      "slug": "notion",
      "displayName": "Notion",
      "category": "productivity",
      "connectFlow": "oauth",
      "status": "disconnected",
      "scopesGranted": [],
      "lastHealthCheckAt": null,
      "lastError": null,
      "metadata": {}
    },
    {
      "slug": "resend",
      "displayName": "Resend",
      "category": "productivity",
      "connectFlow": "api-key",
      "status": "connected",
      "scopesGranted": [],
      "lastHealthCheckAt": "2026-06-16T09:30:00.000Z",
      "lastError": null,
      "metadata": {}
    }
  ]
}

Para iniciar una conexión OAuth pidiendo un subconjunto de scopes (mínimo privilegio), usa la ruta MCP. Los scopes se escriben tal cual los declara el conector; en Google, la URL completa:

# Conectar Gmail solo en modo lectura (subconjunto del preset)
curl -s -X POST https://api.sharasaas.com/mcp/oauth/start \
  -H "Authorization: Bearer $SHARA_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mcpServerName": "gmail", "scopes": ["https://www.googleapis.com/auth/gmail.readonly"] }'

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

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

Al iniciar una conexión se conservan además los scopes que ya habías concedido para el mismo proveedor, de modo que conectar un segundo servicio no apaga el primero. Para conectores api-key, POST /v1/integrations/:slug/connect 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.sharasaas.com/v1/integrations/resend/connect \
  -H "Authorization: Bearer $SHARA_SESSION_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. En POST /mcp/oauth/start, 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). POST /v1/integrations/:slug/connect no valida scopes.
• 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 deja de utilizarse hasta que se reconecte.

Buenas prácticas de configuración

• Pide el mínimo scope necesario. En los conectores que sirve POST /mcp/oauth/start puedes pedir un subconjunto del preset por defecto (por ejemplo, en Teams, solo Team.ReadBasic.All y Channel.ReadBasic.All más offline_access si el agente solo tiene que leer). 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: que un scope exija verificación de la app antes de habilitarse para cuentas externas lo decide Google; compruébalo antes de exponer la conexión a cuentas externas.
• Microsoft: el consentimiento del administrador depende de la configuración de Entra del tenant del cliente. El token de refresco rota en cada renovación.
• Slack: la conexión de empresa pide scopes de bot y el ámbito de usuario search:read (para buscar mensajes).
• CRM (HubSpot, Pipedrive y Salesforce): la ruta de inicio pide siempre el preset completo de arriba; revísalo antes de autorizar.
• API key: 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 MCP gateway o el Server Agent. Cuéntanos tu caso en integraciones@aiginer.com y valoramos añadirlo.