bling.oauth-start

Produces the Bling OAuth2 authorize URL and a signed state token. Front-end redirects the user to authorize_url; bling.oauth-callback validates the returned state.

Generate the Bling authorize URL plus a signed state token.

Overview

Property	Value
Workflow type	Atomic
Library	App-bling
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization initiating the Bling connection
connection_name	string	No	—	Human label for the resulting CloudConnection row
redirect_uri	string	Yes	—	OAuth redirect URI; must match the Bling app config
actor	string	No	—	Caller identity (defaults to context.actor)

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization initiating the Bling connection
connection_name	string	No	—	Human label for the resulting CloudConnection row
redirect_uri	string	Yes	—	OAuth redirect URI; must match the Bling app config
actor	string	No	—	Caller identity (defaults to context.actor)
authorize_url	string	No	—	URL to redirect the end-user to
state	string	No	—	Signed opaque token; pass back unchanged to oauth-callback
initiated_at	string	No	—	ISO-8601 timestamp the URL was generated
failure_reason	string	No	—	Why this run failed (on the failed branch)
failed_at	string	No	—	ISO-8601 timestamp of failure
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	json	No	—	—
failed_layer	json	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
initiated	Yes	No	—	prepare	Request received
failed	No	Yes	No	—	OAuth start failed
ready	No	Yes	Yes	—	Authorize URL produced

State Diagram

Transitions

From	Action	To	Description
initiated	prepare	ready	—
initiated	fail	failed	—

Business Errors

Code	Message Template
BLING_CLIENT_ID_MISSING	BLING_CLIENT_ID is not configured on the platform
BLING_REDIRECT_URI_MISSING	redirect_uri is required for Bling OAuth start

API Usage

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

{
  "workflow_type": "bling.oauth-start",
  "initial_data": {
    "organization_uuid": "value",
    "redirect_uri": "value"
  }
}