Connector Instances

An instance is a connection to a provider. Its owner and its availability in the active workspace are explicit.

Scope	Owner	Availability
personal	The individual who owns the connection	The owner's Personal workspace and explicitly permitted destination workspaces
team	A Business workspace	That exact workspace, subject to membership and permissions

A Personal workspace exposes My connections only. A Business workspace remains Business even with one member. It can expose personal use only when an administrator enables the policy and the connection owner grants that workspace access. Personal and Team instances remain separate even when they use the same provider.

Every request acts in a workspace. Send X-Workspace-Id explicitly when scripting, alongside the bearer token. A connection ID does not grant access in another workspace.

Endpoints

Method	Path	Description	Auth
GET	/connectors/instances	List owned and permitted instances	JWT + active workspace access
POST	/connectors/instances	Create an instance	JWT + plan access + scope-specific management permission
GET	/connectors/instances/:id	Read an available instance	JWT + active workspace access
PATCH	/connectors/instances/:id	Update an instance	JWT + plan access + scope-specific management permission
DELETE	/connectors/instances/:id	Delete an instance	JWT + plan access + scope-specific management permission
POST	/connectors/instances/:id/test	Test a configured connection	JWT + connection access

Who can manage an instance

The Personal owner manages their connection. An owner or admin of the owning Business workspace manages a Team connection. These checks also apply to credentials, OAuth, tool synchronization and custom tools. Plan access never replaces ownership or workspace permissions.

Personal connections used by an automation additionally require owner consent for the exact agent or chain, tool subset, destination workspace and output audience. Personal output is owner-private by default. Workspace sharing must be explicit. Revocation prevents future use; output already explicitly shared remains shared.

Unavailable or disabled connections cannot execute. The same ownership boundary applies to discovery, management, connection tests and tool execution.

Instance Object

The following excerpt shows the ownership and lifecycle fields of a newly created Personal connection. Identifiers and timestamps are illustrative; use the identifiers returned by your request.

{
  "id": "00000000-0000-4000-8000-000000000001",
  "connectorKey": "slack",
  "displayName": "My Slack",
  "status": "pending_auth",
  "enabled": true,
  "scope": "personal",
  "workspaceId": null,
  "availableInWorkspaceId": "00000000-0000-4000-8000-000000000002",
  "ownership": {
    "ownerChainerId": "00000000-0000-4000-8000-000000000003",
    "ownerWorkspaceId": null
  },
  "permissions": {
    "canRead": true,
    "canManage": true,
    "canExecute": false
  },
  "authorizationState": "authorization_required",
  "config": {},
  "lastHealthCheck": null,
  "healthMessage": null,
  "createdAt": "2026-10-02T10:00:00.000Z",
  "updatedAt": "2026-10-02T10:00:00.000Z"
}

Field	Meaning
scope	Explicit personal or team ownership
ownership.ownerChainerId	Personal owner; null for Team connections
ownership.ownerWorkspaceId	Owning Business workspace; null for Personal connections
workspaceId	Owning workspace for Team connections; null for Personal connections
availableInWorkspaceId	Workspace in which this response grants availability
provider	Provider metadata for this authorized connection, or null when unavailable; excludes credentials and authentication configuration
permissions	Current caller's read, management and execution permissions
authorizationState	connected, authorization_required, unavailable, or permission_restricted

Use provider for existing connection display and management, including a Personal connection explicitly permitted in a Business workspace. New installations require a provider available in the active account’s catalog. A missing or inconsistent source provider makes the connection unavailable for execution; its owner retains cleanup access.

Status Values

Value	Meaning
pending_auth	Created, awaiting authentication
active	Activated connection; execution still requires valid credentials, permissions and tools
error	Connection failed
inactive	Disabled connection

Use authorizationState and permissions to present current usability. Status alone is insufficient to authorize execution.

GET /connectors/instances

Lists connections available in the active workspace, including disabled connections so their owner can manage them. It does not list another workspace's Team connections or another individual's Personal connections. A disabled connection or inactive provider has authorizationState: unavailable and cannot execute.

Query parameter	Type	Required	Description
scope	personal or team	No	Filter the already authorized collection by ownership
locale	string	No	Localize provider names and descriptions; English fallback
limit	number	No	Page size; default 20, maximum 100
offset	number	No	Pagination offset; default 0

The response contains data, an array of instance objects, and pagination meta.

curl "$BASE_URL/connectors/instances?scope=personal&limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Set BASE_URL to your API URL including /api/v1. Set TOKEN and WORKSPACE_ID from your authenticated context.

POST /connectors/instances

Creates a connection with status pending_auth. Omitted scope defaults to personal. Team creation requires explicit team scope, an activated Business account and the owning workspace's management permission.

Field	Type	Required	Description
connectorKey	string	Yes	Connector definition key
displayName	string	Yes	Connection name, maximum 255 characters
scope	personal or team	No	Ownership; default personal
config	object	No	Provider-specific configuration

The successful response is 201 with the created instance under data. Save its id for authentication and subsequent requests.

cURL

curl -X POST "$BASE_URL/connectors/instances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"connectorKey":"slack","displayName":"My Slack","scope":"personal"}'

JavaScript

const response = await fetch(`${process.env.BASE_URL}/connectors/instances`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TOKEN}`,
    "X-Workspace-Id": process.env.WORKSPACE_ID,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    connectorKey: "slack",
    displayName: "My Slack",
    scope: "personal",
  }),
});
const { data } = await response.json();

Python

import json, os, urllib.request

request = urllib.request.Request(
    f'{os.environ["BASE_URL"]}/connectors/instances',
    method="POST",
    headers={
        "Authorization": f'Bearer {os.environ["TOKEN"]}',
        "X-Workspace-Id": os.environ["WORKSPACE_ID"],
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "connectorKey": "slack",
        "displayName": "My Slack",
        "scope": "personal",
    }).encode(),
)
with urllib.request.urlopen(request) as response:
    data = json.load(response)["data"]

GET /connectors/instances/:id

Returns the instance under data. The optional locale query parameter localizes its provider metadata with English fallback. An unknown or unavailable foreign ID returns 404; it does not disclose another owner's connection.

curl "$BASE_URL/connectors/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

PATCH /connectors/instances/:id

Updates displayName, config or enabled. Ownership is immutable through this operation.

curl -X PATCH "$BASE_URL/connectors/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"My Slack","enabled":false}'

DELETE /connectors/instances/:id

Permanently deletes user-created connector instances, such as custom MCP servers, only when the caller can manage them in the active workspace. For catalog-provided connections, set enabled to false instead. Foreign IDs cannot be used to delete another owner's connection. Request admission may reject missing plan access before ownership is checked.

curl -X DELETE "$BASE_URL/connectors/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

POST /connectors/instances/:id/test

Tests an authenticated connection. Ownership, lifecycle and provider requirements are checked before a provider is contacted. Creating an instance alone does not make it testable or executable. Configure it through Credentials & OAuth first.