Connectors

A connector is a reusable integration definition — a named bundle of vendor metadata, supported auth schemes, and reusable action templates. Every Smart Plug binds to exactly one connector. Connectors come from two places: the System catalogue shipped by CraftBot, and My Connectors authored by tenant admins for in-house systems.

Auth schemes — static credentials only

CraftBot supports four auth schemes:

Bearer token — the secret is sent as Authorization: Bearer <secret>.
API key (header) — the secret is sent as a custom header (the header name is set in the connector’s helpers).
API key (query) — the secret is appended as a query-string parameter.
Basic — the secret is a base64-encoded user:pass string.

CraftBot does not support OAuth2 in any form, in any phase, on any surface. Connectors for vendors that publicly require OAuth2 (Salesforce, HubSpot, Zoho) ship with their static-token equivalents: Salesforce session-id, HubSpot Private App token, Zoho self-client API key. There is no consent screen, no refresh-token rotation, no token-exchange flow.

System catalogue

The System Connectors section lists the connectors shipped with CraftBot. These are read-only — you can view the details but cannot edit or delete them. Current v1 catalogue:

System connector catalogue with vendor logos for Freshdesk, Generic REST, HubSpot, Salesforce, and Zoho

Generic REST — anything-goes HTTP. Use as the fallback when no vendor-specific connector exists.
Freshdesk — ticket CRUD on the Freshdesk help-desk platform.
Zoho Desk — ticket CRUD on Zoho’s help-desk.
Zoho CRM — contact and deal CRUD on Zoho’s CRM.
HubSpot Service Hub — ticket CRUD on HubSpot.
Salesforce Service Cloud — case CRUD on Salesforce.

Click View on any row to see the full action list, supported auth schemes, vendor helpers, and documentation URL.

Authoring a tenant connector

For an in-house system not in the catalogue (a TPA core platform, an internal CRM, an analytics service), tenant admins author their own connector under My Connectors.

Settings → Connectors → + New Connector.
The form opens with four tabs:

Identity

Name — the human-readable label (e.g. TPA Core API).
Vendor — the underlying system (e.g. NEXtCARE).
Key — a stable machine name. Immutable after create.
Version — semver-ish string for your own change tracking.
Icon — optional design-system icon name.
Documentation URL — link to the vendor’s API docs. Surfaces in the Smart Plug authoring UI.
Description — markdown-formatted notes for fellow admins.

Auth

Tick every auth scheme the connector should expose to Smart Plugs. Most connectors expose one. Multi-tick is supported when the underlying API accepts multiple auth flavours.

Actions

A JSON array of action templates. Each action carries an HTTP method, path, headers, body template, input list, and a response schema. Smart Plug buttons later pick from this list rather than re-defining the HTTP call.

The v1 editor is raw JSON — paste in a structured definition and let the server validate it. A form-based action editor is a follow-up.

Helpers

A JSON object of vendor-specific helpers — base URL, the header name when API key (header) auth is used, status colours, URL templates, brand colour, vendor logo URL. Smart Plugs and the agent panel read these to render consistent UI without each plug re-declaring them.

Editing and deleting

Tenant connectors support the standard Edit / Delete affordances. Editing rewrites the action list and helpers in place — Smart Plugs already bound to the connector continue to work, but actions removed from the array will start failing the next time a button picks them.

System connectors are read-only. To customise one, duplicate the action JSON into a new tenant connector with a different key.

Best practices

Start every tenant deployment by reviewing the system catalogue. If your help-desk is Freshdesk, use the shipped Freshdesk connector — don’t author a custom one.
For TPA core or other proprietary systems, build one tenant connector with the right actions, then point every Smart Plug at it. This keeps auth and vendor helpers in one place.
Treat the version field as documentation, not enforcement. Bump it when you change the action list so other admins know the shape changed.
Don’t hand-edit the action JSON in production. Author in a staging tenant, paste the validated JSON across.