Understanding Connectors and Connections

Learn the difference between connectors and connections in Spojit.

Overview

Connectors and connections are two layers of the same idea, and Spojit keeps them deliberately separate. A connector is the template (what a service is and what it can do). A connection is your workspace's configured instance of that template (with credentials and any per-instance settings). Workflows reference connections, never connectors directly.

Keeping the two layers apart means you can update a connector (new tools added by Spojit) without touching your credentials, and rotate credentials on a connection without rebuilding workflows. It also lets a single workspace hold multiple connections to the same connector - typical for multi-store, multi-region, or staging vs production setups.

Connector

A connector is a global template that defines an integration. Connectors are maintained by Spojit and shared across every workspace. A connector specifies:

Identity - Name, icon, category (e.g. E-commerce, Databases).
Authentication scheme - OAuth, API key, basic auth, webhook, or no auth.
Tools - The operations the integration exposes (e.g. list_products, create_order).
Input and output schemas - The shape of each tool's arguments and results.

Connection

A connection is your workspace's configured instance of a connector. It is workspace-scoped and holds:

Display name - How the connection appears in pickers and logs.
Credentials - The encrypted key, token, or OAuth tokens for this specific instance.
Service URL - For self-hosted services or instance-specific endpoints (e.g. https://yourshop.myshopify.com).
Visibility - Workspace-wide. Anyone in the workspace who can build workflows can reference the connection, but the underlying credential is never exposed in the UI after saving.
Status - Active, Reauthorize, or Error based on the most recent verification or call.

Example

The Shopify connector is a single template that defines the Shopify integration: it uses OAuth, exposes tools like list_products and create_order, and is the same in every workspace. Your workspace might have two Shopify connections: Shopify - AU Store and Shopify - US Store. Each holds its own OAuth tokens and points at a different store. A workflow uses a Connector node and picks the specific connection it should run against.

How Workflows Reference Connections

A workflow's Connector node stores the connection ID, not the credential.
Rotating a credential on the connection has no effect on the workflow definition.
Renaming a connection does not break workflows; they continue to resolve by ID.
Deleting a connection breaks every workflow that references it - the next run will fail.

Tips

Treat connections as long lived. Rotate credentials in place rather than creating a new connection.
Name connections to disambiguate environment and instance (Stripe - Production, MySQL - Reporting Replica).
Create separate connections for staging and production so you cannot accidentally hit live systems from a test workflow.

Common Pitfalls

Confusing connector with connection - Adding a "new Shopify connector" is not a thing; you add a new connection to the Shopify connector.
Deleting a connection still referenced by workflows - Workflows fail silently until their next run. Check usage before removing.
Sharing personal OAuth connections - The connection acts on behalf of the original authorizer. If that person leaves or revokes access, the shared connection dies.