Getting Started with Connectors

Connectors are integrations that let your AI agents interact with external services -- Slack, Gmail, Google Drive, Notion, Asana, Airtable, Vercel, Stripe, and more. Each connector provides a set of tools that agents can call during workflows or that you can invoke directly via the API and CLI.

Think of connectors as bridges between your Chainabit workspace and the services your team already uses.

How Connectors Work

Install a connector instance in your workspace
Authenticate by linking your account on the external service (OAuth, API key, etc.)
Enable tools that the connector provides
Use tools in agent workflows, call them from the API, or run them from the CLI

Each connection has an explicit owner: an individual for Personal connections, or the active Business workspace for Team connections. Personal workspaces never expose Team connections. A Business workspace keeps its type even with one member.

An individual manages their own Personal connection. Owners and admins manage connections owned by their Business workspace. Personal use in Business requires an administrator policy and explicit owner consent for that workspace. Plan access and tool permissions remain enforced. See Who can manage an instance.

Runtime identity and agent access

A connector definition (for example, Google Drive), a connected instance (for example, Company Drive), and a tool (for example, list_files) are different identities. When more than one instance of a connector exists, Chainabit resolves an exact connection; it never chooses the first matching account.

Agents receive access through a separate, workspace-scoped attachment to an exact connection. Publishing, cloning, or versioning an agent never transfers a user's connector credentials.

If a requested connection is missing, stale, ambiguous, or not attached to an agent, the runtime emits a structured requirement. Clients perform the requested interaction, then resume the original run. They must not replace the requested connector with a generic search result.

Tool Access modes

Mode	Runtime behavior
`on_demand` (default)	Tool schemas remain unloaded until an exact connector connection is required. Expansion remains scoped to that connection.
`eager`	Authorized connector catalogs are prepared at run start. The model receives schemas within its tool/context budget; remaining catalog entries stay discoverable and can be expanded without loading unrelated connectors.

The saved Tool Access preference belongs to the account settings. Selected connection instances belong to the chat session or current run, not global preferences.

Quick Start

Prerequisites

A Chainabit account with a valid access token
An active workspace
Ownership of a Personal connection, or the owner or admin role in an activated Business workspace for a Team connection (Steps 2 and 3), with the required plan access

Set your environment variables:

bash

export BASE_URL="https://api.chainabit.com/api/v1"
export TOKEN="your-access-token"

Step 1 -- Choose a Connector

Browse the available connectors:

CLIcURLJavaScriptPython

bash

chainabit connectors list

bash

curl "$BASE_URL/connectors" \
  -H "Authorization: Bearer $TOKEN"

javascript

const response = await fetch(`${BASE_URL}/connectors`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await response.json();

python

import requests

response = requests.get(
    f"{BASE_URL}/connectors",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()["data"]

Step 2 -- Install a Connector Instance

Create a Personal connection in your active workspace. Set WORKSPACE_ID to its identifier:

CLIcURLJavaScriptPython

bash

chainabit connectors install slack --name "My Slack" --scope personal

bash

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"]

Response 201 Created

The instance object in the response includes ownership and permissions. Identifiers below are illustrative.

json

{
  "data": {
    "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"
  }
}

Save the instance id -- you will need it for authentication and tool execution.

Step 3 -- Authenticate

Most connectors use OAuth. Start the authorization flow:

CLIcURL

bash

chainabit connectors auth inst_abc123

bash

curl -X POST "$BASE_URL/connectors/instances/inst_abc123/oauth/initiate" \
  -H "Authorization: Bearer $TOKEN"

Follow the returned URL to authorize access on the external service. Chainabit handles the token exchange automatically.

For connectors that use API keys or connection strings, store credentials directly:

bash

curl -X POST "$BASE_URL/connectors/instances/inst_abc123/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credType": "api_key",
    "credentials": { "apiKey": "your-key" }
  }'

Step 4 -- Test the Connection

CLIcURL

bash

chainabit connectors test inst_abc123

bash

curl -X POST "$BASE_URL/connectors/instances/inst_abc123/test" \
  -H "Authorization: Bearer $TOKEN"

Step 5 -- Use in Workflows or Call Directly

Once authenticated, the connector's tools are available to your agents. You can also execute tools that do not require approval directly:

CLIcURL

bash

chainabit connectors exec inst_abc123 list_channels \
  --input '{"limit": 20}'

bash

curl -X POST "$BASE_URL/connectors/instances/inst_abc123/tools/tool_list_channels/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "limit": 20
    }
  }'

Tools that change data in the external service, such as Slack send_message, require approval. Direct execution refuses them with 403; ask Chao to run them instead, which applies its approval rules before acting.

Connector Catalog

The full catalog is grouped by family and mirrored in English and Turkish. Start with the Connector Catalog, then open the connector-specific pages you need.

Featured Connectors

Connector	Key	Category	Auth Method	Description
Slack	`slack`	Communication	OAuth	Send messages, manage channels, search
Gmail	`gmail`	Communication	OAuth	Send and read emails, manage drafts
Google Drive	`google-drive`	Productivity	OAuth	Manage files and folders
Google Calendar	`google-calendar`	Productivity	OAuth	Manage calendar events
Notion	`notion`	Productivity	OAuth / API key	Search and manage pages, databases
Canva	`canva`	Design	OAuth	Create and export designs
SQL Database	`sql-database`	Database	Connection string	Query PostgreSQL or MySQL
MCP Server	`mcp-generic`	Protocol	API key / Bearer	Connect to any MCP-compatible server

Connector Lifecycle

Pending -- Connector is installed but not yet authenticated
Active -- Connector is authenticated and ready to use
Error -- Health check failed or credentials expired
Inactive -- Connector has been manually disabled

Security

Credentials are encrypted at rest and never returned in API responses
OAuth tokens are refreshed automatically before they expire
Team connections belong to their owning Business workspace. Personal connections require an explicit owner binding to each destination workspace.
All tool executions are logged in the audit trail
You can revoke credentials at any time

Next Steps

Explore the Connector Catalog by family, then set up your first connector
Learn about the CLI commands for managing connectors
See the API reference for programmatic access
Build a custom connector for your own services

Getting Started with Connectors ​

How Connectors Work ​

Runtime identity and agent access ​

Tool Access modes ​

Quick Start ​

Prerequisites ​

Step 1 -- Choose a Connector ​

Step 2 -- Install a Connector Instance ​

Step 3 -- Authenticate ​

Step 4 -- Test the Connection ​

Step 5 -- Use in Workflows or Call Directly ​

Connector Catalog ​

Featured Connectors ​

Connector Lifecycle ​

Security ​

Next Steps ​

Getting Started with Connectors

How Connectors Work

Runtime identity and agent access

Tool Access modes

Quick Start

Prerequisites

Step 1 -- Choose a Connector

Step 2 -- Install a Connector Instance

Step 3 -- Authenticate

Step 4 -- Test the Connection

Step 5 -- Use in Workflows or Call Directly

Connector Catalog

Featured Connectors

Connector Lifecycle

Security

Next Steps