Skip to content

Working with Connections

Connections define reusable endpoints and credential configurations for your workflows. They represent physical or logical integrations (like an API, SFTP server, or Message Broker).

Type-First Management

Within MeshFlows, connections are managed primarily by their Type. The type determines which configuration properties are available and how the platform handles authentication.

Common types include: - http: REST/Web APIs with optional OAuth 2.0. - ssh: Remote execution via SSH (type: ssh). - sftp: File transfers over SFTP (type: sftp — distinct from ssh). - ftp: Legacy FTP/FTPS transfers. - s3: S3-compatible object storage (including MinIO). - postgres: PostgreSQL for SQL capability providers. - rabbitmq: AMQP 0.9.1 message exchange. - positionstack / weatherstack / joke-api: Registry-driven HTTP API providers.

Registry-driven providers need no orchestrator env changes — deploy the egress service and reference connections in workflow service_call steps. See Deploy integration contract and Connections Reference.

Custom connection type (new capability provider)

When you add a new egress provider, register a kind: workflow_connection capability whose metadata.designer.connection_type matches the YAML type:. Example (Weatherstack-shaped):

name: weatherstack
type: weatherstack
access_key: "$secret:weatherstack-access-key"

The provider owns the field list (designer form_fields); Orchestrator merges those fields into the service_call body. Full path: Integration end-to-end. Field catalog: Connections reference.

Connection Lifecycle

Connections can be defined in two ways: 1. Repository-based: Defined in flows/connections/*.yaml. These are versioned and deployed with your code. 2. Dashboard/Runtime-managed: Overridden or created directly via the Connections panel in the Dashboard.

Note: Changes made in the Dashboard are stored in the Runtime Store and take precedence over repository files for immediate lifecycle management.

Examples

HTTP with OAuth 2.0 (Client Credentials)

The http type supports automatic OAuth 2.0 bearer token caching and refresh.

name: salesforce_api
type: http
base_url: https://your-instance.salesforce.com
oauth:
  token_url: https://login.salesforce.com/services/oauth2/token
  client_id: "$secret:sf-client-id"
  client_secret: "$secret:sf-client-secret"
  scope: "api"

SFTP with Private Key

name: crm_export_ftp
type: sftp
host: sftp.example.com
port: 22
username: "svc_meshflows"
private_key_pem: "$secret:transfer-ssh-key"

IMAP with Gmail

Use an App Password, not the normal Google account password.

name: google_mailbox
type: imap
host: imap.gmail.com
port: 993
username: your-account@gmail.com
password: "$secret:google-imap-app-password"
use_ssl: true

Gmail checklist: - Enable IMAP in Gmail settings for the mailbox. - Enable Google 2-Step Verification. - Generate an App Password and store it as a runtime secret. - Reference that secret in the connection using $secret:<name>.

Dashboard Management

The Dashboard provides a structured view of all active connections: - Grouped by Type: Connections are organized by their protocol (HTTP, SFTP, etc.) for better overview. - YAML Editing: You can perform "small edits" (like updating a base_url or port) directly by clicking a connection and choosing Edit YAML. - Secret Masking: While you can point to secrets using $secret:name, the dashboard will never expose the underlying sensitive values.

  • Metadata in Git: Keep non-sensitive connection metadata in your repository.
  • Secrets in Stores: Reference secrets by name; do not commit actual values.
  • Logical Names: Use descriptive names like inventory_service rather than api_server_01.

How to create, deploy, and verify runtime secrets (Dashboard, API, CI sync): Deploy MeshFlows Runtime Secrets.