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)OAuthClientCredentialsobject 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.
ssh¶
Remote command execution via the SSH egress (egress.ssh.exec, …).
host: Target hostname or IP.port: Default is22.username: Login user.password: (Optional) Login password.private_key_pem: (Optional) SSH private key in PEM format.
Example in repo: flows/connections/example_secret_ssh.yaml (type: ssh).
sftp¶
File transfer over SSH/SFTP (sftp.list / download / upload, or egress.ssh.sftp). Same host/auth fields as SSH, but type: sftp — not interchangeable with ssh for capability connection_type matching.
Example: flows/connections/sftp_demo.yaml.
ftp¶
Legacy FTP/FTPS transfers (egress.ftp / FTP capability).
protocol: e.g.ftpshost,port(default21),username,password
Example: flows/connections/example_secret_ftp.yaml (type: ftp).
s3¶
Object storage (AWS S3-compatible, including in-cluster MinIO).
endpoint: Service URL (e.g.http://orchestrator-minio:9000)region: e.g.us-east-1secure: TLS to endpoint (true/false)default_bucket: Default bucket name- Optional
access_key/secret_keyvia$secret:(omitted for pod-default MinIO demos)
Examples: flows/connections/s3.yaml, flows/connections/minio_demo.yaml (type: s3).
postgres¶
PostgreSQL for SQL capability providers.
host,port(default5432),database,username,passwordsslmode: e.g.prefer
Example: flows/connections/postgres.yaml.
joke-api¶
Official Joke API provider connection (type: joke-api). No base URL credentials in the demo file — reference as connection: joke-api on egress.joke-api.* steps.
Example: flows/connections/joke-api.yaml.
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, orheaders.
imap¶
Used for reading e-mails from an IMAP mailbox.
host: IMAP server hostname (e.g.imap.gmail.com).port: Default is993.username: Mailbox username/e-mail address.password: Mailbox password or app-specific token.use_ssl: (Optional) Default istrue.
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 is587.username: SMTP username.password: SMTP password.use_tls: (Optional) Use STARTTLS (port 587 default). Default istrue.use_ssl: (Optional) Use Implicit SSL (port 465 default). Default isfalse.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 (subclaim).scopes: OAuth scopes granted for this connection.
Authentication model:
- Orchestrator resolves connection + secrets.
- Orchestrator calls
egress-google-workspacewith connection auth payload. - Egress service signs JWT with service-account private key.
- Egress service exchanges JWT for Google access token.
- 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 (
calendaronly,driveonly, 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.
azure-servicebus¶
Azure Service Bus topics + subscriptions via egress-azure-servicebus.
auth:connection_string(default) orworkload_identity(ADR 0012)connection_string: SAS string (use$secret:). Required whenauthisconnection_string.fully_qualified_namespace:myns.servicebus.windows.net. Required whenauthisworkload_identity.client_id: optional user-assigned MI client id (otherwise the podAZURE_CLIENT_ID)- Optional defaults:
topic,subscription
Example: flows/connections/azure-servicebus.yaml. Cluster federation example: engine/deploy/k8s/azure-workload-identity.example.yaml.
Custom types from capability providers¶
New connection type values come from a provider’s workflow_connection registration (metadata.designer.connection_type), not from a hard-coded Orchestrator enum. To add one: register the connection capability, ship flows/connections/<name>.yaml, and reference connection: on service_call — Integration end-to-end, Contract — workflow connection example.
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.