Connectors / BYOK

A connector is a configured edge between 10ex and a third-party provider. Connectors carry both credentials (an OAuth grant or BYOK key) and a role.

• Source. Agents read from this provider. Apollo for enrichment, HubSpot for lead data.
• Sink. Agents write to this provider. Gmail for sending, HubSpot for CRM updates, Webflow for blog publish.
• Both. Common for CRMs.

The role distinction is currently best-effort metadata and is being formalized. See the tech debt note “Run-required vs action-required connectors are not first-class” in 10ex_fastapi/TECH_DEBTS.md.

BYOK

For LLM, ad-platform, and enrichment providers, you can bring your own API key. The trade-off: 10ex skips the data-fee component of the agent’s credit_cost, and you pay the provider directly. The orchestration fee still applies. Full split-fee implementation is also tech debt.

A concrete example: if you BYOK Apollo, Marcus/Prospector still costs 1 credit per batch (orchestration), but the per-lead enrichment fee goes to your Apollo account, not ours.

Why agents can refuse to run

If an agent declares a required_connector and that connector isn’t connected for the workspace, the agent refuses rather than fails mid-execution. This protects you from spending credits on a run that was never going to finish. Use list_connectors and get_agent_details to gate runs from MCP.

A common gotcha: connecting Gmail in your personal account vs the workspace account. Connectors are workspace-scoped, so make sure you’re authenticating with the right Google identity. The connector list under Settings → Integrations shows which workspace owns each grant.

Common questions

Are credentials encrypted at rest? Yes. OAuth tokens and BYOK keys are encrypted in the connector store; they’re never exposed in the UI after creation.

What happens when a token expires? The connector flips to a “needs reauth” state and any agent that depends on it refuses to run until you reconnect.

Can I share connectors across workspaces? No. Each workspace has its own connector store, by design.

Related

• Platform mental model: where connectors sit in the broader architecture
• Roles & permissions: only Admins can add or remove connectors