connection.setup

Sets up a new cloud provider connection by validating credentials, testing connectivity, persisting to database, and syncing resources

Workflow for setting up cloud provider connections.

States: initiated → validating → testing → persisting → syncing → completed any → failed

Overview

Property	Value
Workflow type	Linear
Library	App-connection
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization that owns the connection
provider_type	string	Yes	—	Cloud provider key (aws, gcp, azure, cloudflare, github, route53, lovable, ...)
connection_name	string	No	—	Human-friendly name for the connection
dialect	string	No	—	SQL dialect (postgres v1; mysql/etc. later)
host	string	No	—	SQL database hostname or IP
port	string	No	—	SQL database TCP port (default 5432 for postgres)
database	string	No	—	SQL database / catalog name
ssl_mode	string	No	—	Postgres sslmode (disable, allow, prefer, require, ...)
username	string	No	—	SQL database username, or the MCP HTTP Basic username
actor	string	No	—	Authenticated caller (Cognito sub or UUID) initiating the workflow
role_arn	string	No	—	AWS IAM role ARN to assume
external_ref	string	No	—	External ID for AWS STS:AssumeRole (auto-generated when missing)
regions	list	No	—	AWS regions the connection should cover
region	string	No	—	Default region (Azure / single-region providers)
aws_connection_uuid	uuid	No	—	Existing AWS CloudConnection.uuid (Route53 reuse)
zone_mode	string	No	—	Route53 hosted-zone selection mode
zone_refs	list	No	—	Route53 hosted-zone references
service_account_json	json	No	—	GCP service-account key (JSON object)
project_ref	string	No	—	GCP project reference; derived from service_account_json when omitted
authorization_code	string	No	—	iFood distributed authorization code returned after the merchant enters their user code
authorization_code_verifier	string	No	—	iFood verifier that completes the authorization-code exchange; a secret, not a correlation id
refresh_token	string	No	—	GCP OAuth refresh token (OAuth path)
tenant_ref	string	No	—	Azure AD tenant reference
tenant_id	string	No	—	Magalu Cloud project tenant UUID (x-tenant-id)
auth_mode	string	No	—	Magalu auth mode: api_key, oauth, or object_storage
key_pair_id	string	No	—	Magalu Object Storage key pair ID
key_pair_secret	string	No	—	Magalu Object Storage key pair secret
client_ref	string	No	—	Provider application client reference (Azure, iFood, etc.)
client_secret	string	No	—	Provider application secret (Azure, iFood, etc.)
subscription_ref	string	No	—	Azure subscription reference
app_connection_uuid	uuid	No	—	iFood application connection this merchant authorizes through. When set, the merchant connection stores no application secret of its own
api_token	string	No	—	Bearer/API token credential
api_key	string	No	—	Generic API key credential
personal_access_token	string	No	—	Account-level personal access / admin token (Wasender)
session_id	string	No	—	Provider session identifier (Wasender WhatsApp session)
webhook_secret	string	No	—	Shared secret used to verify inbound provider webhooks
sap_environment	string	No	—	SAP data environment: 'sandbox' (Accelerator Hub, default) or 'live'
account_ref	string	No	—	Provider account reference (Cloudflare, etc.)
team_ref	string	No	—	Provider team/organization reference (Vercel)
base_url	string	No	—	Self-hosted / OpenAI-compatible provider base URL
azure_endpoint	string	No	—	Azure OpenAI resource endpoint (https://{resource}.openai.azure.com)
api_version	string	No	—	Azure OpenAI API version query (e.g. 2024-02-01)
custom_domain	string	No	—	Custom domain override for self-hosted instances
header_name	string	No	—	MCP: header to carry the API key (default X-API-Key)
auth_scheme	string	No	—	MCP: Authorization scheme prefix (default Bearer)
resource_url	string	No	—	MCP: RFC 9728 protected-resource identifier
authorization_server	string	No	—	MCP: issuer of the authorization server backing this resource
authorize_endpoint	string	No	—	MCP: RFC 8414 authorization endpoint
token_endpoint	string	No	—	MCP: RFC 8414 token endpoint
registration_endpoint	string	No	—	MCP: RFC 7591 dynamic client registration endpoint
registered_via_dcr	boolean	No	—	MCP: client_id was created by dynamic client registration
token_expires_at	string	No	—	MCP: ISO-8601 expiry of the current access token
scopes	json	No	—	MCP: list of OAuth scopes granted for this connection
extra_headers	json	No	—	MCP: additional static headers to send on every request
redirect_uri	string	No	—	MCP: primary OAuth callback registered on the DCR client
redirect_uris	json	No	—	MCP: all OAuth callbacks registered on the DCR client
organization	string	No	—	Organization slug for providers that scope by org
installation_ref	integer	No	—	GitHub App installation reference
access_token	string	No	—	OAuth access token
app_ref	string	No	—	Meta App ID reference (optional; for future token exchange)
app_secret	string	No	—	Meta App Secret (optional; for future token exchange)
graph_api_version	string	No	—	Meta Graph API version (default v21.0)
default_page_ref	string	No	—	Default Meta Page reference for organic publishing
instagram_business_account_ref	string	No	—	Linked Instagram Business Account reference
user_access_token	string	No	—	Long-lived Meta User token for Page/IG discovery
page_access_token	string	No	—	Page access token for the default Meta Page publish target
pages	json	No	—	Cached Meta Pages + IG refs from connection.meta.sync-assets
channel_ref	string	No	—	YouTube channel reference (organic)
channels	json	No	—	Cached YouTube channel inventory from connection.youtube.sync-assets
organization_ref	string	No	—	Organization pin (Deere org id or LinkedIn Community URN)
organizations	json	No	—	Cached org inventory from connection.deere.sync-assets or linkedin-community.sync-assets
ad_account_ref	string	No	—	Ads account reference (meta_ads / linkedin_ads)
ad_accounts	json	No	—	Cached Meta Ads ad-account inventory from connection.meta-ads.sync-assets
conversions_api_key	string	No	—	OpenAI Ads Conversions API key (server-side event sends to bzr.openai.com)
pixel_id	string	No	—	OpenAI Ads Pixel ID used as the default data source for Conversions API sends
docusign_auth_mode	string	No	—	DocuSign auth mode: user_oauth (default) or org_jwt
docusign_environment	string	No	—	DocuSign environment: developer (default) or production
docusign_account_ref	string	No	—	DocuSign account reference (GUID) pin; the userinfo default account when omitted
docusign_user_ref	string	No	—	DocuSign API user reference (GUID) an org_jwt connection impersonates
docusign_rsa_private_key	string	No	—	RSA private key (PEM) registered on the DocuSign integration key (org_jwt)
accounts	json	No	—	Cached DocuSign account inventory from oauth-exchange userinfo
customer_ref	string	No	—	Google Ads customer / account reference
developer_token	string	No	—	Google Ads API developer token
account	json	No	—	Authenticated X user {id, username, name, profile_image_url} from oauth-exchange
api_secret	string	No	—	Provider API secret
bot_token	string	No	—	Slack bot token (xoxb-...)
signing_secret	string	No	—	Slack request signing secret
enterprise_ref	string	No	—	Slack enterprise/team grid reference
bot_user_ref	string	No	—	Slack bot user reference
access_key_ref	string	No	—	Alibaba Cloud access key reference
access_key_secret	string	No	—	Alibaba Cloud access key secret
endpoint_url	string	No	—	S3-compatible endpoint URL (Neon branch storage endpoint)
s3_endpoint	string	No	—	Alias for endpoint_url (Neon Object Storage)
branch_ref	string	No	—	Neon branch reference (label only for neon_storage)
auth_method	string	No	—	Sentry auth method
token	string	No	—	Sentry auth token
organization_slug	string	No	—	Sentry organization slug
project_slug	string	No	—	Sentry project slug
expires_at	string	No	—	ISO-8601 expiry of the current OAuth access_token
scope	string	No	—	OAuth scope string granted by the provider
company_ref	string	No	—	Provider-side account/company reference (Bling)
kubernetes_auth_mode	string	No	—	Kubernetes auth mode: static, incluster_service_account, gke_delegated, or eks_delegated
kubernetes_provider_connection_uuid	uuid	No	—	Same-organization GCP/AWS connection used for delegated token minting
kubernetes_cluster_location	string	No	—	Cluster region or location used by delegated authentication
kubernetes_cluster_name	string	No	—	Provider cluster name used by delegated authentication
kubeconfig	string	No	—	Full kubeconfig YAML; parsed server-side into the three discrete fields
api_server	string	No	—	Kubernetes API server URL (https://...); overrides parsed kubeconfig server when set
bearer_token	string	No	—	ServiceAccount or static bearer token
ca_certificate	string	No	—	Cluster CA bundle (PEM)
namespace_default	string	No	—	Default Kubernetes namespace for ops that don't carry one

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization that owns the connection
provider_type	string	Yes	—	Cloud provider key (aws, gcp, azure, cloudflare, github, route53, lovable, ...)
connection_name	string	No	—	Human-friendly name for the connection
dialect	string	No	—	SQL dialect (postgres v1; mysql/etc. later)
host	string	No	—	SQL database hostname or IP
port	string	No	—	SQL database TCP port (default 5432 for postgres)
database	string	No	—	SQL database / catalog name
ssl_mode	string	No	—	Postgres sslmode (disable, allow, prefer, require, ...)
actor	string	No	—	Authenticated caller (Cognito sub or UUID) initiating the workflow
role_arn	string	No	—	AWS IAM role ARN to assume
regions	list	No	—	AWS regions the connection should cover
region	string	No	—	Default region (Azure / single-region providers)
aws_connection_uuid	uuid	No	—	Existing AWS CloudConnection.uuid (Route53 reuse)
zone_mode	string	No	—	Route53 hosted-zone selection mode
zone_refs	list	No	—	Route53 hosted-zone references
project_ref	string	No	—	GCP project reference; derived from service_account_json when omitted
tenant_ref	string	No	—	Azure AD tenant reference
tenant_id	string	No	—	Magalu Cloud project tenant UUID (x-tenant-id)
auth_mode	string	No	—	Magalu auth mode: api_key, oauth, or object_storage
client_ref	string	No	—	Provider application client reference (Azure, iFood, etc.)
subscription_ref	string	No	—	Azure subscription reference
app_connection_uuid	uuid	No	—	iFood application connection this merchant authorizes through. When set, the merchant connection stores no application secret of its own
session_id	string	No	—	Provider session identifier (Wasender WhatsApp session)
sap_environment	string	No	—	SAP data environment: 'sandbox' (Accelerator Hub, default) or 'live'
account_ref	string	No	—	Provider account reference (Cloudflare, etc.)
team_ref	string	No	—	Provider team/organization reference (Vercel)
base_url	string	No	—	Self-hosted / OpenAI-compatible provider base URL
azure_endpoint	string	No	—	Azure OpenAI resource endpoint (https://{resource}.openai.azure.com)
api_version	string	No	—	Azure OpenAI API version query (e.g. 2024-02-01)
custom_domain	string	No	—	Custom domain override for self-hosted instances
header_name	string	No	—	MCP: header to carry the API key (default X-API-Key)
auth_scheme	string	No	—	MCP: Authorization scheme prefix (default Bearer)
resource_url	string	No	—	MCP: RFC 9728 protected-resource identifier
authorization_server	string	No	—	MCP: issuer of the authorization server backing this resource
authorize_endpoint	string	No	—	MCP: RFC 8414 authorization endpoint
token_endpoint	string	No	—	MCP: RFC 8414 token endpoint
registration_endpoint	string	No	—	MCP: RFC 7591 dynamic client registration endpoint
registered_via_dcr	boolean	No	—	MCP: client_id was created by dynamic client registration
token_expires_at	string	No	—	MCP: ISO-8601 expiry of the current access token
scopes	json	No	—	MCP: list of OAuth scopes granted for this connection
extra_headers	json	No	—	MCP: additional static headers to send on every request
redirect_uri	string	No	—	MCP: primary OAuth callback registered on the DCR client
redirect_uris	json	No	—	MCP: all OAuth callbacks registered on the DCR client
organization	string	No	—	Organization slug for providers that scope by org
installation_ref	integer	No	—	GitHub App installation reference
app_ref	string	No	—	Meta App ID reference (optional; for future token exchange)
app_secret	string	No	—	Meta App Secret (optional; for future token exchange)
graph_api_version	string	No	—	Meta Graph API version (default v21.0)
default_page_ref	string	No	—	Default Meta Page reference for organic publishing
instagram_business_account_ref	string	No	—	Linked Instagram Business Account reference
user_access_token	string	No	—	Long-lived Meta User token for Page/IG discovery
page_access_token	string	No	—	Page access token for the default Meta Page publish target
pages	json	No	—	Cached Meta Pages + IG refs from connection.meta.sync-assets
channel_ref	string	No	—	YouTube channel reference (organic)
channels	json	No	—	Cached YouTube channel inventory from connection.youtube.sync-assets
organization_ref	string	No	—	Organization pin (Deere org id or LinkedIn Community URN)
organizations	json	No	—	Cached org inventory from connection.deere.sync-assets or linkedin-community.sync-assets
ad_account_ref	string	No	—	Ads account reference (meta_ads / linkedin_ads)
ad_accounts	json	No	—	Cached Meta Ads ad-account inventory from connection.meta-ads.sync-assets
pixel_id	string	No	—	OpenAI Ads Pixel ID used as the default data source for Conversions API sends
docusign_auth_mode	string	No	—	DocuSign auth mode: user_oauth (default) or org_jwt
docusign_environment	string	No	—	DocuSign environment: developer (default) or production
docusign_account_ref	string	No	—	DocuSign account reference (GUID) pin; the userinfo default account when omitted
docusign_user_ref	string	No	—	DocuSign API user reference (GUID) an org_jwt connection impersonates
docusign_rsa_private_key	string	No	—	RSA private key (PEM) registered on the DocuSign integration key (org_jwt)
accounts	json	No	—	Cached DocuSign account inventory from oauth-exchange userinfo
customer_ref	string	No	—	Google Ads customer / account reference
account	json	No	—	Authenticated X user {id, username, name, profile_image_url} from oauth-exchange
enterprise_ref	string	No	—	Slack enterprise/team grid reference
bot_user_ref	string	No	—	Slack bot user reference
endpoint_url	string	No	—	S3-compatible endpoint URL (Neon branch storage endpoint)
s3_endpoint	string	No	—	Alias for endpoint_url (Neon Object Storage)
branch_ref	string	No	—	Neon branch reference (label only for neon_storage)
auth_method	string	No	—	Sentry auth method
organization_slug	string	No	—	Sentry organization slug
project_slug	string	No	—	Sentry project slug
expires_at	string	No	—	ISO-8601 expiry of the current OAuth access_token
scope	string	No	—	OAuth scope string granted by the provider
company_ref	string	No	—	Provider-side account/company reference (Bling)
kubernetes_auth_mode	string	No	—	Kubernetes auth mode: static, incluster_service_account, gke_delegated, or eks_delegated
kubernetes_provider_connection_uuid	uuid	No	—	Same-organization GCP/AWS connection used for delegated token minting
kubernetes_cluster_location	string	No	—	Cluster region or location used by delegated authentication
kubernetes_cluster_name	string	No	—	Provider cluster name used by delegated authentication
api_server	string	No	—	Kubernetes API server URL (https://...); overrides parsed kubeconfig server when set
ca_certificate	string	No	—	Cluster CA bundle (PEM)
namespace_default	string	No	—	Default Kubernetes namespace for ops that don't carry one
connection_uuid	uuid	No	—	UUID of the persisted connection (set by persist step)
initiated_at	string	No	—	ISO-8601 timestamp when setup was initiated
initiated_by	string	No	—	Actor that initiated the setup
validation_passed	boolean	No	—	True after credentials validated
validated_at	string	No	—	ISO-8601 timestamp of validation
test_passed	boolean	No	—	True after connectivity test
test_result	json	No	—	Provider connectivity test result
account_info	json	No	—	Provider account metadata returned by test_connection (forwarded to persist)
tested_at	string	No	—	ISO-8601 timestamp of connectivity test
persisted	boolean	No	—	True when persist step wrote a row
persisted_at	string	No	—	ISO-8601 timestamp of persist
restored	boolean	No	—	True when persist restored a soft-deleted row
sync_skipped	boolean	No	—	True when DNS sync was skipped
sync_reason	string	No	—	Reason DNS sync was skipped
zones_synced	integer	No	—	Zones written/updated by DNS sync
records_synced	integer	No	—	Records written/updated by DNS sync
sync_completed_at	string	No	—	ISO-8601 timestamp of DNS sync completion
sync_error	string	No	—	DNS sync error message
sync_failed_at	string	No	—	ISO-8601 timestamp of DNS sync failure
completed_at	string	No	—	ISO-8601 timestamp of overall completion
failure_reason	string	No	—	Failure reason on the failed branch
failure_type	string	No	—	Failure category
failed_action	string	No	—	Action method that raised
failed_at_state	string	No	—	State the workflow was in when it failed
failed_at	string	No	—	ISO-8601 timestamp of failure
error	string	No	—	Engine-stamped exception message
error_type	string	No	—	Engine-stamped exception class name
failed_layer	string	No	—	Engine-stamped layer index (DAG path)
failed_step	string	No	—	Engine-stamped step name (DAG path)
retried_from	string	No	—	Previous terminal state restored by engine retry
retry_count	integer	No	—	Number of retry attempts recorded by the engine

States

State	Initial	Terminal	Success	Auto-advance	Description
initiated	Yes	No	—	validate_credentials	Connection request received, normalizing input
persisting	No	No	—	sync_resources	Saving connection to database
syncing	No	No	—	complete	Syncing DNS resources from provider
testing	No	No	—	persist_connection	Testing connection to cloud provider
validating	No	No	—	test_connection	Validating credentials format
completed	No	Yes	Yes	—	Connection successfully established
failed	No	Yes	No	—	Connection setup failed

State Diagram

Transitions

From	Action	To	Description
initiated	validate_credentials	validating	—
validating	test_connection	testing	—
testing	persist_connection	persisting	—
persisting	sync_resources	syncing	—
syncing	complete	completed	—
initiated	fail	failed	—
validating	fail	failed	—
testing	fail	failed	—
persisting	fail	failed	—
syncing	fail	failed	—

Business Errors

Code	Message Template
UNSUPPORTED_PROVIDER	Unsupported provider type:
INVALID_CREDENTIALS
CONNECTION_TEST_FAILED	Connection test failed:
AWS_CONNECTION_NOT_FOUND	AWS connection {connection_uuid} not found
AWS_CONNECTION_INACTIVE	AWS connection {connection_uuid} is not active

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "connection.setup",
  "initial_data": {
    "organization_uuid": "value",
    "provider_type": "value"
  }
}