connection.oauth-start

Begin a provider OAuth authorization-code flow (returns authorize URL + state)

Begin a provider OAuth 2.0 authorization-code flow.

Inputs:

• provider_type: OAuth provider key (gcp, bling, github, aws, ...) (required)
• organization_uuid: UUID of the org that will own the connection (required)
• connection_name: optional name to carry through to setup
• 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 (else the platform default)

Outputs (terminal state_data):

• provider_type: str
• project_ref: str | None
• region: str | None
• tenant_id: str | None
• authorization_url: str # provider consent URL to redirect the user to
• state: str # signed CSRF/state token, verified on exchange
• expires_at: str # ISO-8601 expiry of the state token
• error: str | None # only on failure

No client secret is involved — only the public client_id / redirect_uri / scopes.

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, ...)
organization_uuid	uuid	Yes	—	UUID of the org that will own the connection
connection_name	string	No	—	Optional name carried through to connection.setup
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	—	LinkedIn organization URN to pin after organic OAuth grant
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; else the platform default
connection_uuid	uuid	No	—	Existing connection whose discovered OAuth endpoints drive the flow. Required for providers that resolve their authorization server per connection (mcp).

Output Schema

Field	Type	Required	Default	Description
provider_type	string	No	—	Echoed provider key
organization_uuid	uuid	No	—	Echoed organization UUID
connection_name	string	No	—	Echoed connection name carried to exchange
redirect_uri	string	No	—	Echoed redirect URI used to build the authorize URL
connection_uuid	uuid	No	—	Echoed connection whose endpoints drove the flow (dynamic providers)
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	—	LinkedIn organization URN to pin after organic OAuth grant
ad_account_ref	string	No	—	Meta Ads ad account ID (act_…) to pin after Marketing API OAuth grant
authorization_url	string	No	—	Provider consent URL to redirect the user to
state	string	No	—	Signed state token (CSRF; verified on exchange)
expires_at	string	No	—	ISO-8601 expiry of the state token
error	string	No	—	Error message when start 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-start",
  "initial_data": {
    "provider_type": "value",
    "organization_uuid": "value"
  }
}