Connectors

A connector is a reusable definition of a third-party system you can call from automations and logic blocks. Connectors are wired across three tiers, joined by a durable connector_id.

The three tiers

• Platform admin defines the connector — its auth type, the credential form, the available actions, and an allowed-domains list.
• Org admin builds the automation — picks the connector and action and maps source fields to the action's inputs.
• Each workspace saves its own credentials — encrypted, never returned by any API.

1 · The connector definition (platform)

POST /admin/connector
{
  "connector_id": "salesforce",
  "display_name": "Salesforce",
  "auth_type": "api_key",
  "auth_schema": { "fields": [{ "name": "api_key", "label": "API Key", "type": "password", "required": true }] },
  "actions": [{
    "action_id": "create-contact",
    "http_method": "POST",
    "url_template": "https://api.salesforce.com/v1/contacts",
    "body_schema": [{ "name": "Email", "label": "Email" }]
  }],
  "allowed_domains": ["*.salesforce.com"],
  "enabled": true
}

• `auth_schema.fields` drives the credential form tenants fill in.
• `actions` are what org admins can pick in an automation.
• `allowed_domains` — the executor refuses any hostname that doesn't match.
• `enabled` — a platform kill-switch; disabled connectors are silently skipped.

2 · Tenant credentials

Each workspace stores credentials as a settings record (group = connector, name = connector_id). The fields are AES-256 encrypted before storage. A tenant can connect, opt out (enabled: false), or leave it unconfigured — the last two are silently skipped at runtime.

{
  "group": "connector",
  "name": "salesforce",
  "value": { "enabled": true, "encrypted_config": "<ciphertext of { api_key }>" }
}

Runtime safety

When an automation fires, the executor loads the connector, resolves the workspace's credentials, resolves the URL template, and runs layered domain checks before making the call.

• Must be HTTPS and not a private IP (SSRF protection).
• The hostname must match the connector's allowed_domains.
• The hostname must match the org's allowlist, if one is configured.