Skip to content

Connections Reference

Connections are reusable endpoint and credential definitions. The MeshFlows Orchestrator uses these definitions to handle low-level protocol details, authentication, and connection pooling.

Connection Schema by Type

http

Used for API integrations. Supports standard HTTP/HTTPS and OAuth 2.0.

  • base_url: Prefix for step URLs.
  • default_headers: (Optional) Map of headers added to every request.
  • oauth: (Optional) OAuthClientCredentials object for automatic token management.
  • token_url: The OAuth 2.0 token endpoint.
  • client_id: Client identifier.
  • client_secret: Client secret.
  • scope: Space-separated string of requested scopes.

Bearer Caching: When OAuth is configured, the orchestrator automatically caches the bearer token and refreshes it 30 seconds before expiry.

sftp / ssh

Used for secure file transfers and remote command execution.

  • host: Target hostname or IP.
  • port: Default is 22.
  • username: Login user.
  • password: (Optional) Login password.
  • private_key_pem: (Optional) SSH private key in PEM format.

rabbitmq

Configuration for AMQP 0.9.1 integration.

  • url: Full AMQP connection URL (e.g., amqp://user:pass@host:5672/vhost).
  • exchange: Default exchange for publishing (default: meshflows.events).
  • exchange_type: topic, direct, fanout, or headers.

imap

Used for reading e-mails from an IMAP mailbox.

  • host: IMAP server hostname (e.g. imap.gmail.com).
  • port: Default is 993.
  • username: Mailbox username/e-mail address.
  • password: Mailbox password or app-specific token.
  • use_ssl: (Optional) Default is true.

Gmail-specific requirements: - Use host: imap.gmail.com and port: 993 with use_ssl: true. - Enable IMAP in Gmail settings for the mailbox. - Enable Google 2-Step Verification and use an App Password. - Do not use the regular Google account password for IMAP; it is rejected. - Store the App Password as a secret and reference it as $secret:<name> in the connection.

smtp

Used for sending e-mails via an SMTP server.

  • host: SMTP server hostname (e.g. smtp.gmail.com).
  • port: Default is 587.
  • username: SMTP username.
  • password: SMTP password.
  • use_tls: (Optional) Use STARTTLS (port 587 default). Default is true.
  • use_ssl: (Optional) Use Implicit SSL (port 465 default). Default is false.
  • default_from: (Optional) Default "From" address if not specified in the step.

google_workspace

Used for Gmail, Calendar, and Drive connector steps through the dedicated egress-google-workspace microservice.

  • service_account_key: Full Google service-account JSON string (recommended via $secret: reference).
  • impersonate_user: (Optional) User e-mail for domain-wide delegation (sub claim).
  • scopes: OAuth scopes granted for this connection.

Authentication model:

  1. Orchestrator resolves connection + secrets.
  2. Orchestrator calls egress-google-workspace with connection auth payload.
  3. Egress service signs JWT with service-account private key.
  4. Egress service exchanges JWT for Google access token.
  5. Token is cached and reused until expiry.

Recommended setup:

  • Store service-account JSON in runtime secrets ($secret:google-workspace-sa-key).
  • Keep scopes least-privilege per connection (calendar only, drive only, etc.).
  • Enable domain-wide delegation only when required.
  • Never commit raw private keys to Git.

positionstack

Geocoding via the egress-positionstack capability provider (registry discovery, no orchestrator URL env).

  • access_key: Positionstack API access key (use $secret: reference).
name: positionstack
type: positionstack
access_key: "$secret:positionstack-access-key"

Workflow steps use service_call with capabilities such as egress.positionstack.forward or egress.positionstack.reverse. See Egress Positionstack.

weatherstack

Weather data via the egress-weatherstack capability provider (registry discovery, no orchestrator URL env).

  • access_key: Weatherstack API access key (use $secret: reference).
name: weatherstack
type: weatherstack
access_key: "$secret:weatherstack-access-key"

Workflow steps use service_call with capabilities such as egress.weatherstack.current, egress.weatherstack.historical, or egress.weatherstack.forecast. See Egress Weatherstack.

Management via Dashboard

The Dashboard (Connections tab) displays these connections grouped by their type. You can: - View Current State: See the merged configuration (Git + Overrides). - In-place Edit: Update specific fields like host or base_url directly via the YAML editor. - Audit: Verify which connections are active in the current deployment.