connection.rotate.credentials

Validates replacement credentials, tests them, updates the existing connection, and marks it active

Rotate or repair credentials for an existing cloud connection.

Public callers use this workflow instead of data.connection.update. The wrapper accepts either the spec-level new_credentials object or the same flattened credential fields used by connection.setup.

Overview

Property	Value
Workflow type	Atomic
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
connection_uuid	uuid	Yes	—	UUID of the connection whose credentials should be rotated
new_credentials	json	No	—	Replacement credential payload; flattened fields are also accepted
candidate_credentials	json	No	—	Alias accepted by repair flows for replacement credentials
dry_run	boolean	No	—	Validate and test without mutating the stored connection
rotation_strategy	string	No	—	Caller supplied rotation mode or policy key
reconcile_dependents	boolean	No	—	Whether dependent resources should be reconciled after rotation
idempotency_key	string	No	—	Caller supplied idempotency key for safe retries

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 connection whose credentials were rotated
dry_run	boolean	No	—	True when the workflow skipped mutation
rotation_strategy	string	No	—	Caller supplied rotation mode or policy key
reconcile_dependents	boolean	No	—	Caller requested dependent reconciliation
idempotency_key	string	No	—	Caller supplied idempotency key
initiated_at	string	No	—	ISO-8601 timestamp when rotation began
initiated_by	string	No	—	Actor that initiated rotation
validation_passed	boolean	No	—	True after credential validation
validated_at	string	No	—	ISO-8601 timestamp of credential validation
test_passed	boolean	No	—	True after replacement credentials tested successfully
test_result	json	No	—	Provider connectivity test result
account_info	json	No	—	Provider account metadata returned by the test
tested_at	string	No	—	ISO-8601 timestamp of connectivity test
updated_fields	list	No	—	Fields changed by data.connection.update
updated_at	string	No	—	ISO-8601 timestamp of credential update
new_status	string	No	—	Connection status after status update
last_validated_at	string	No	—	ISO-8601 timestamp of last successful validation
validation_count	integer	No	—	Total validations performed on the row
status	string	No	—	Workflow-level status
summary	json	No	—	Workflow summary
warnings	list	No	—	Non-fatal warnings
completed_at	string	No	—	ISO-8601 timestamp when rotation completed
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
failed_step	string	No	—	Engine-stamped step name

States

State	Initial	Terminal	Success	Auto-advance	Description
initiated	Yes	No	—	rotate	Credential rotation request received
completed	No	Yes	Yes	—	Credentials rotated
failed	No	Yes	No	—	Credential rotation failed

State Diagram

Transitions

From	Action	To	Description
initiated	rotate	completed	—
* (any state)	fail	failed	—

API Usage

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

{
  "workflow_type": "connection.rotate.credentials",
  "initial_data": {
    "organization_uuid": "value",
    "provider_type": "value",
    "connection_uuid": "value"
  }
}