Connections

Overview

The Connections hub is the single home for every external credential your workspace uses. Each connection exposes one or more tools that agents and workflow Tool nodes can call, using the slug.operation naming convention. Connections come in two transports:

AI model providers (OpenAI, Anthropic, Gemini), search tools, and messaging accounts (Gmail, Telegram bots) are also managed here as connections — they share the same encrypted credential store. Once added, every connection's tools appear alongside built-in tools in the agent tool picker and the workflow Tool node inspector.

Service types

When you create a connection you pick a service type. It determines the transport, the available auth methods, and how tools are defined:

HTTP & OpenAPI

Create an HTTP connection from Connections → New Connection. For a generic REST API choose HTTP API; to import a spec choose OpenAPI. You will set:

• Name & slug — the slug is used as the tool prefix (e.g. github → tools named github.create_issue).
• Base URL — the root URL of the API.
• Auth type — none, API key (header or query), Bearer token, or Basic auth.
• Operations — each operation has a name, HTTP method, path, and optional input/output parameter schemas.

Operation path templating

Path and query parameters use {{param}} syntax and are filled from the agent's tool call arguments at runtime:

GET /repos/{{owner}}/{{repo}}/issues/{{number}}

Importing a spec

The OpenAPI service type lets the wizard do the work for you:

1. Choose OpenAPI in the New Connection wizard.
2. Paste the spec as JSON or YAML, or upload the file. The importer extracts servers[0] as the base URL, securitySchemes as the auth type, and all paths as operations.
3. Review and edit the parsed operations, adjust parameter schemas if needed, then save.

MCP servers

Chatterfly connects to MCP servers using Streamable HTTP or SSEtransport. The server's tools/list response defines all available tools.

1. In Connections → New Connection, choose the MCP Server service type.
2. Enter the MCP server URL (e.g. https://mcp.example.com/sse) and optional Bearer credentials.
3. The backend connects to the server, calls tools/list, and previews the discovered tool definitions.
4. Review the discovered tools and save the connection.

Tool naming convention

Every connection tool follows the slug.operation format:

Slugs are unique within your workspace. If you rename or delete a connection, all references to its tools in deployed workflows will fail at runtime — update them before deleting.

Using tools in agents

Open an agent in Agents. The tool picker shows two sections — Standard tools (built-in) and Connections (your HTTP/MCP tools). Select any combination.

Alternatively, specify tools directly in the agent JSON:

{
  "name": "Support Agent",
  "tools": [
    "web_search",
    "github.create_issue",
    "stripe.retrieve_customer"
  ]
}

The agent runner resolves built-in tool names from the registry first; if no match is found, it parses the name as slug.operation and looks up the connection in the database.

Using tools in workflows

Add a Tool node to your workflow in the visual editor. In the Tool Inspector, set tool_name to the full slug.operation string:

{
  "id": "create-ticket",
  "type": "tool",
  "tool_name": "github.create_issue",
  "input": {
    "owner": "acme",
    "repo":  "support",
    "title": "{{steps.triage.output.summary}}"
  }
}

Tool input values support {{path.to.value}} template expressions that are resolved from workflow state at execution time. The node runs, captures the response, and the workflow advances — it does not wait for a human ( that is what a surface does).

Fulfillment

Fulfillment decides where the credentials come from when a workflow uses a connection. Choose one when you create or edit it:

Credential management

Chatterfly supports the following authentication types for HTTP connections:

Storage & encryption

All credential values are encrypted with AES-256-GCM using the INTEGRATION_ENCRYPTION_KEY environment variable before being stored in the database. They are decrypted in-memory at execution time only and are never returned in any API response.

SSRF protection

The connection executor rejects requests targeting private, loopback, or link-local IP ranges (RFC1918, 127.0.0.0/8, 169.254.0.0/16, etc.) to prevent server-side request forgery.

Personal account connections

Connections with caller (per-run) fulfillment use the credentials of whoever triggers the run. Platform users pre-authorize their accounts once under Settings → My Accounts; stored credentials are then injected automatically whenever they trigger a run — no tokens are pasted into run dialogs.

Permission tiers

OAuth providers expose capability tiers so users grant only the access a workflow needs — for example Gmail offers send, read, and full tiers, each mapping to specific OAuth scopes. The tiers selected at connect time determine the scopes requested during the provider consent flow, and connected cards show which tiers were granted.

Configuring providers (operators)

Each OAuth provider needs client credentials, configured via either of these explicit sources (the admin registry takes precedence):

1. Admin registry — Platform Admin → OAuth Providers. Secrets are encrypted at rest and can be rotated at runtime without a redeploy.
2. Environment variables — CONNECT_<ID>_CLIENT_ID / CONNECT_<ID>_CLIENT_SECRET (e.g. CONNECT_GMAIL_CLIENT_ID).

A connect app must be configured explicitly through one of these — there is no implicit reuse of the platform's login OAuth credentials.

Register this redirect URI with the OAuth provider:

<APP_URL>/api/auth/connect/<provider>/callback

AI providers & platform services

API keys for AI model providers and built-in tools are managed in an encrypted database registry — not environment variables. Platform operators set platform-wide keys under Platform Admin → Service Credentials, and workspace admins can bring their own keys for overridable services under Settings → Workspace → AI & Services.

Services

Resolution precedence

For each request, the key is resolved in order: your workspace key (if the service is tenant-overridable and you saved one) → platform key → a clear “not configured” error. There is no environment-variable fallback for these services.

Write-only secrets

Keys are encrypted with AES-256-GCM before storage and are never returned by any API. When editing an existing credential, leaving a field blank keeps the current value — enter a new value only to rotate it. Removing your workspace key reverts the service to the platform key.