connection.oauth-exchange

Exchange an OAuth code for tokens and run connection.setup

Finish a provider OAuth authorization-code flow (code -> tokens -> connection.setup).

Inputs:

• provider_type: OAuth provider key (gcp, bling, github, aws, ...) (required)
• code: authorization code the provider returned to the callback (required)
• state: signed state token from connection.oauth-start (required)
• organization_uuid: UUID of the org that will own the connection (required)
• connection_name: optional name for the connection
• project_ref: GCP project ID to persist with the OAuth connection
• region: provider region to persist with the OAuth connection
• tenant_id: Magalu Cloud project tenant UUID (x-tenant-id)
• redirect_uri: optional callback URL override (must match the start call)

Outputs (terminal state_data):

• connection_uuid: str # from connection.setup
• status: str # connection status after setup
• provider_type: str
• error: str | None # only on failure

The client SECRET is read ONLY inside this workflow and never returned/logged/stored in state_data; tokens flow straight into connection.setup (encrypted at rest).

Overview

Property	Value
Workflow type	Atomic
Library	App-connection
Version	1.0

Input Schema

Field	Type	Required	Default	Description
provider_type	string	Yes	—	OAuth provider key (gcp, bling, github, aws, ...)
code	string	Yes	—	Authorization code returned to the callback
state	string	Yes	—	Signed state token from connection.oauth-start
organization_uuid	uuid	Yes	—	UUID of the org that will own the connection
connection_name	string	No	—	Optional name for the connection
project_ref	string	No	—	GCP project ID to persist with the OAuth connection
account_ref	string	No	—	Provider account reference to persist with the OAuth connection
team_ref	string	No	—	Provider team reference to persist with the OAuth connection
tenant_ref	string	No	—	Provider tenant reference to persist with the OAuth connection
subscription_ref	string	No	—	Provider subscription reference to persist with the OAuth connection
region	string	No	—	Provider region to persist with the OAuth connection
tenant_id	string	No	—	Magalu Cloud project tenant UUID (x-tenant-id) to persist with the OAuth connection
enterprise_ref	string	No	—	Provider enterprise reference to persist with the OAuth connection
bot_user_ref	string	No	—	Provider bot/user reference to persist with the OAuth connection
default_page_ref	string	No	—	Meta Page ID to pin after organic OAuth grant
instagram_business_account_ref	string	No	—	Instagram Business account ID to pin after organic OAuth grant
channel_ref	string	No	—	YouTube channel ID to pin after organic OAuth grant
organization_ref	string	No	—	Organization reference to pin after OAuth grant (Deere org id or LinkedIn URN)
ad_account_ref	string	No	—	Meta Ads ad account ID (act_…) to pin after Marketing API OAuth grant
redirect_uri	string	No	—	Callback URL override (must match the start call)

Output Schema

Field	Type	Required	Default	Description
connection_uuid	uuid	No	—	UUID of the connection created by connection.setup
status	string	No	—	Connection status after setup
provider_type	string	No	—	Echoed provider key
error	string	No	—	Error message when exchange failed
failure_reason	string	No	—	Engine-stamped failure reason
failure_type	string	No	—	Engine-stamped failure category
failed_action	string	No	—	Engine-stamped action that raised
failed_at_state	string	No	—	Engine-stamped state name when the workflow failed
failed_step	string	No	—	Engine-stamped step name (DAG path)
failed_layer	string	No	—	Engine-stamped layer index (DAG path)
error_type	string	No	—	Engine-stamped exception class name

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

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

{
  "workflow_type": "connection.oauth-exchange",
  "initial_data": {
    "provider_type": "value",
    "code": "value",
    "state": "value",
    "organization_uuid": "value"
  }
}