37  Enterprise Connectors

37.1 Overview

Sophea Automations takes a different approach to connectors than generic automation tools. Instead of offering hundreds of connectors to external SaaS apps, Sophea focuses on controlled, enterprise-grade connectors that are scoped to tenants, respect permission boundaries, and integrate with the RAG pipeline.

37.2 How connectors are scoped to tenants

37.2.1 Tenant isolation

Every connector in Sophea is scoped to a workspace (tenant). When a flow step lists available connectors via the broker, the response only includes connectors that belong to the requesting workspace. The broker endpoint:

  1. Resolves the tenant ID from the workspace membership
  2. Opens a tenant-scoped database session
  3. Queries fetch_connectors() filtered by tenant
  4. Returns only connectors with DocumentSource.INGESTION_API (API-sourced connectors)

This means a flow in Workspace A can never see or access connectors from Workspace B.

37.2.2 Permission sync

Connector permissions are synced from the Portal. When a workspace member runs a flow, the broker:

  1. Verifies the user is an active member of the workspace (_verify_runtime_member)
  2. Builds signed ACL principals based on the user’s email and workspace membership
  3. Propagates the ACL to the RAG service for search operations

The ACL ensures that flow steps can only access documents that the requesting user has permission to see. If a user does not have access to a document set, no flow step they trigger can access it either.

37.3 RAG grounding

37.3.1 What is RAG grounding?

RAG (Retrieval-Augmented Generation) grounding means that AI actions in flows always have access to the workspace knowledge base. Instead of sending prompts to an LLM with no context, Sophea actions search the indexed knowledge base first, then pass the retrieved chunks as context to the LLM.

37.3.2 How it works

  1. A flow step calls ask_nous_knowledge with a question
  2. The broker endpoint builds signed ACL principals for the requesting user
  3. The broker calls run_batch_search() on the RAG service, passing the signed ACL
  4. The RAG service searches the vector index, filtering by ACL
  5. Retrieved chunks are passed as context to the LLM
  6. The LLM generates an answer grounded in the retrieved documents
  7. The answer is returned to the flow step with citations

37.3.3 Available RAG actions

Action Description
ask_nous_knowledge Ask a question, get a grounded answer with citations
search_knowledge Search the knowledge base, get raw chunks
batch_search_knowledge Run multiple searches in one step
fetch_chunks Fetch all chunks for a specific document

37.3.4 ACL enforcement in RAG

The RAG service enforces ACL at the query level. When a search request arrives:

  1. The X-Sophea-Principals header is verified (HMAC signature)
  2. The signed ACL is decoded: {tid, uid, pr, exp}
  3. If the tenant ID or user ID does not match the request, the search returns 401
  4. The vector search filters results to only include documents matching the ACL
  5. If the ACL is expired or missing, the behavior depends on REQUIRE_SIGNED_PRINCIPALS:
    • off (default): fall back to body acl_principals
    • warn: log a warning, fall back to body acl_principals
    • enforce: return 401

37.4 Connector types

37.4.1 Sophea piece (native)

The Sophea piece provides 21 actions and 4 triggers that are native to the platform:

  • Knowledge: ask_nous_knowledge, search_knowledge, batch_search_knowledge, fetch_chunks
  • AI: ask_workspace_model, run_nous_agent
  • Agent lifecycle: start_agent_run, get_agent_run_status, cancel_agent_run, get_agent_run_artifacts
  • Approvals: request_human_approval, create_approval_task, llm_approval
  • Workspace: list_connectors, list_workspace_users, list_workspace_teams, fetch_saved_searches, notify_workspace, send_workspace_email
  • Documents: upload_document, get_document_status
  • Triggers: agent_run_completed, document_indexed, connector_sync_completed, connector_sync_failed

37.4.2 Shell-mode allowlist

In shell mode, only vetted pieces are available (18 pieces total):

  • @activepieces/piece-sophea (all Sophea actions and triggers)
  • @activepieces/piece-manual-trigger (manual trigger)
  • @activepieces/piece-schedule (time-based triggers)
  • @activepieces/piece-webhook (HMAC-signed webhook trigger)
  • @activepieces/piece-tables (data tables)
  • @activepieces/piece-forms (forms and human input)
  • @activepieces/piece-file-helper (file operations)
  • @activepieces/piece-csv (CSV operations)
  • @activepieces/piece-data-mapper (data transformation)
  • @activepieces/piece-data-summarizer (data summarization)
  • @activepieces/piece-date-helper (date utilities)
  • @activepieces/piece-delay (delay step)
  • @activepieces/piece-math-helper (math operations)
  • @activepieces/piece-pdf (PDF operations)
  • @activepieces/piece-qrcode (QR code generation)
  • @activepieces/piece-store (key-value storage)
  • @activepieces/piece-text-helper (text utilities)
  • @activepieces/piece-xml (XML operations)

37.4.3 External connectors

External connectors (e.g., Slack, Google Drive, Confluence) are available outside shell mode. They are managed through the standard connector framework and respect tenant isolation at the connection level. Each connection is scoped to a workspace.

37.5 Security model

Layer Mechanism
Transport HMAC-signed HTTP between Automations API and Nous backend
Tenant Workspace ID verified on every broker call
User Runtime member verification (active workspace membership)
Data Signed ACL principals propagated to RAG service
Execution Sandboxed piece execution with vetted allowlist
Webhooks HMAC signature verification on incoming webhooks