Begin provider authorization

Get a configured provider consent URL; complete browser consent separately before discovering connection metadata.

Outcome

Get a configured provider consent URL; complete browser consent separately before discovering connection metadata.

Before you start

Verify authenticated identity, environment and the approved organization context before preparing an action.
The published application permission is workspace:write. Bind a granted Flow workspace for request access, while the connection data and effects cover the whole authenticated organization. A workspace header does not narrow connection scope.
Session callers need admin workspace access. Auth-introspected API keys must bind that workspace and satisfy workspace:write. The application permission and workspace boundary are separate checks.

Discover the target

topolo whoami --json
topolo actions get app_topolo_flow.connections.oauth.start --detail --json
topolo resources topolo-flow --json
topolo workspaces list topolo-flow --json

Set FLOW_WORKSPACE_ID to the exact id returned by granted workspace discovery.

Request

GET /api/connections/oauth/{provider}/start

Inspect and test this action. Save the exact input object as payload.json; resource context is supplied separately.

Input fields

Field	Required	Meaning	Constraints
`provider`	Required	Normalized provider identifier; the handler accepts letters, digits, underscore, dot, colon and hyphen.	{"minLength":1,"maxLength":80}

View the full input schema through the action reference or CLI/MCP discovery.

Effects

Returns a provider consent URL containing a ten-minute HMAC-signed state for the authenticated organization and caller. This read creates no connection or local database row. It still requires workspace:write and a granted Flow workspace.
Uses provider credentials resolved for the exact configured development, staging or production Auth host, and the configured provider redirect URI or declared Flow public host. A configured service secret is required; no built-in signing secret is used.
Opening the returned URL initiates a separate browser consent journey. Only a successful provider callback and Nexus upsert can create organization-wide connection metadata; returning a URL is not proof of consent, tokens or a connected provider.
Session callers need admin access to the exact granted Flow workspace, in addition to the published application permission. Auth-introspected API keys use their bound workspace and workspace:write; supplying an id never grants access.

Interpret the response

Returns an ephemeral consent URL, not a connection id. Discover created connection metadata through connections.list after the separate consent callback.

Inspect the returned provider authorization URL and its redirect_uri for the selected environment. No connection is created by this read. After separately authorized browser consent and a successful callback, call connections.list and inspect the exact provider, connection id and lifecycle status. These local fixtures do not prove live provider eligibility, custody or consent.

View the complete success schema. Success examples below preserve the actual exported Worker responses; errors have their original refusal shapes. CLI/MCP add their transport envelope, and --detail requests the full CLI response.

Worked examples

Captured from the actual exported Flow Worker with both local SQLite D1 stores and all committed migrations, synthetic Auth identity/grants and simulated Nexus, archive and Workflow-acceptance transports. Fixture credentials and identifiers authorize no live operation. No live provider invocation, credential storage, notification delivery, metering acceptance, durable Workflow execution, deployment, backup erasure or production completion is established by these captures. Refused examples explain boundaries and must not be executed as successful workflows.

Refused request · HTTP 502

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof. Scenario: OAuth credential dependency unavailable.

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 502:

{
  "error": "oauth_credentials_unavailable"
}

HTTP 502. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Successful request

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --detail --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_flow.connections.oauth.start",
    "input": {
      "provider": "fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "url": "https://provider.fixture.test/authorize?response_type=code&client_id=synthetic-provider-client&redirect_uri=https%3A%2F%2Fflow.topolo.dev%2Fapi%2Fconnections%2Foauth%2Fcallback&scope=fixture%3Aread&state=eyJwcm92aWRlciI6ImZpeHR1cmUiLCJvcmdJZCI6Im9yZ19mbG93X2ZpeHR1cmUiLCJ1c2VySWQiOiJ1c3JfZmxvd19maXh0dXJlIiwidHMiOjE3OTEyMTg1MTQzMzJ9.a22sYDJvd3xPt36DiKWD7caKue1KNtnpWS2ln6ZgHF0"
}

HTTP 200. Inspect the returned provider authorization URL and its redirect_uri for the selected environment. No connection is created by this read. After separately authorized browser consent and a successful callback, call connections.list and inspect the exact provider, connection id and lifecycle status. These local fixtures do not prove live provider eligibility, custody or consent.

Refused request · HTTP 503

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 503:

{
  "error": "oauth_not_configured"
}

HTTP 503. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Refused request · HTTP 403

Input · payload.json:

{
  "provider": "synthetic_missing"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 403:

{
  "error": "This workspace requires admin access",
  "code": "workspace_access_insufficient"
}

HTTP 403. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Another supported response

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --detail --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_flow.connections.oauth.start",
    "input": {
      "provider": "fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "url": "https://provider.fixture.test/authorize?response_type=code&client_id=synthetic-provider-client&redirect_uri=https%3A%2F%2Fflow.topolo.app%2Fapi%2Fconnections%2Foauth%2Fcallback&scope=fixture%3Aread&state=eyJwcm92aWRlciI6ImZpeHR1cmUiLCJvcmdJZCI6Im9yZ19mbG93X2ZpeHR1cmUiLCJ1c2VySWQiOiJ1c3JfZmxvd19maXh0dXJlIiwidHMiOjE3OTEyMTg1MTQzNDh9.P8elwA-xuozQzCGSntGDa4a0kbRPbfXyWbJPfjOugNo"
}

Refused request · HTTP 401

Input · payload.json:

{
  "provider": "synthetic_missing"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 401:

{
  "error": "Authentication token required"
}

HTTP 401. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Refused request · HTTP 404

Input · payload.json:

{
  "provider": "unconfigured"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 404:

{
  "error": "provider_not_configured"
}

HTTP 404. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Another supported response

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --detail --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_flow.connections.oauth.start",
    "input": {
      "provider": "fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "url": "https://provider.fixture.test/authorize?response_type=code&client_id=synthetic-provider-client&redirect_uri=https%3A%2F%2Fflow.stg.topolo.us%2Fapi%2Fconnections%2Foauth%2Fcallback&scope=fixture%3Aread&state=eyJwcm92aWRlciI6ImZpeHR1cmUiLCJvcmdJZCI6Im9yZ19mbG93X2ZpeHR1cmUiLCJ1c2VySWQiOiJ1c3JfZmxvd19maXh0dXJlIiwidHMiOjE3OTEyMTg1MTQzNDN9.egiNgvli52CTZqmUQ4YZ5UJtGyOj_T2nu0Z5KGEmDwc"
}

Refused request · HTTP 403

Input · payload.json:

{
  "provider": "synthetic_missing"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 403:

{
  "error": "This workspace requires admin access",
  "code": "workspace_access_insufficient"
}

HTTP 403. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Another supported response

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --detail --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_flow.connections.oauth.start",
    "input": {
      "provider": "fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "url": "https://provider.fixture.test/authorize?response_type=code&client_id=synthetic-provider-client&redirect_uri=https%3A%2F%2Fflow.flow-fixture.test%2Fapi%2Fconnections%2Foauth%2Fcallback&scope=fixture%3Aread&state=eyJwcm92aWRlciI6ImZpeHR1cmUiLCJvcmdJZCI6Im9yZ19mbG93X2ZpeHR1cmUiLCJ1c2VySWQiOiJ1c3JfZmxvd19maXh0dXJlIiwidHMiOjE3OTEyMTg1MTYyODJ9.2WN7gJLua_Qr-6kOd-JVEcOuhAyUBG7bAEJ7LrBEP30"
}

Refused request · HTTP 403

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 403:

{
  "success": false,
  "error": {
    "code": "action_permission_required",
    "message": "Action \"connections.oauth.start\" requires permission \"workspace:write\".",
    "action": "connections.oauth.start"
  }
}

HTTP 403. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Refused request · HTTP 502

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 502:

{
  "error": "oauth_credentials_unavailable"
}

HTTP 502. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Another supported response

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --detail --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_flow.connections.oauth.start",
    "input": {
      "provider": "fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "url": "https://provider.fixture.test/authorize?response_type=code&client_id=synthetic-provider-client&redirect_uri=https%3A%2F%2Fcallback.fixture.test%2Fprovider&scope=fixture%3Aread&state=eyJwcm92aWRlciI6ImZpeHR1cmUiLCJvcmdJZCI6Im9yZ19mbG93X2ZpeHR1cmUiLCJ1c2VySWQiOiJ1c3JfZmxvd19maXh0dXJlIiwidHMiOjE3OTEyMTg1MTQ5MTd9.62_9LA1IDVKz0EirOGZFQkQQSGaEN9y_2jlG0ll-VwY"
}

Refused request · HTTP 503

Input · payload.json:

{
  "provider": "fixture"
}

CLI:

topolo actions validate app_topolo_flow.connections.oauth.start --data @payload.json --json
topolo actions plan app_topolo_flow.connections.oauth.start --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 503:

{
  "error": "oauth_not_configured"
}

HTTP 503. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Verify the result

Inspect the returned provider authorization URL and its redirect_uri for the selected environment. No connection is created by this read.
After separately authorized browser consent and a successful callback, call connections.list and inspect the exact provider, connection id and lifecycle status. These local fixtures do not prove live provider eligibility, custody or consent.

Errors and recovery

Authentication token required (HTTP 401): Authenticate normally in the approved environment and organization, verify identity, then rediscover the action and its granted resource before retrying.
organization_required (HTTP 403): Authenticate into the specifically approved organization. Do not guess a different organization or bypass the refusal.
action_permission_required (HTTP 403): The credential lacks the exact published application permission. Stop and obtain authorized access; changing target ids cannot grant it.
workspace_required (HTTP 400): Discover an explicitly granted Flow workspace and bind its exact resource id.
provider_not_configured (HTTP 404): An authorized operator must configure the provider OAuth application for this exact environment before consent can begin.
oauth_not_configured (HTTP 503): The environment requires its declared Flow public host and configured service signing secret. Do not substitute production settings or a shared default secret.
oauth_credentials_unavailable (HTTP 502): OAuth credential resolution failed, including unavailable Nexus transport or an unknown Auth environment. Verify the configured environment and dependency health before retrying.
workspace_access_insufficient (HTTP 403): Stop when the selected workspace grant is insufficient. Obtain authorized admin access, or an Auth-introspected key with the correct workspace binding and workspace:write; do not widen context or retry with guessed ids.

Preserve the exact status, response, request id and resource context. Runtime input validation, authentication and platform resource resolution can refuse a request before the handler. Dynamic dependency messages are not stable provider error codes.

Recovery boundary

Retry consent URL discovery after authorized environment/provider configuration is healthy. Do not reuse an expired URL or infer a connection from URL creation. After a completed consent callback read connections.list and verify the exact provider and connection metadata; token exchange and provider consent remain separate outcomes.

List Flow connections: Read organization-wide provider connection metadata owned by Nexus for Flow.

Evidence

Captured from the actual exported Flow Worker with both local SQLite D1 stores and all committed migrations, synthetic Auth identity/grants and simulated Nexus, archive and Workflow-acceptance transports. Fixture credentials and identifiers authorize no live operation. No live provider invocation, credential storage, notification delivery, metering acceptance, durable Workflow execution, deployment, backup erasure or production completion is established by these captures. Original scenario labels and response digests are retained in the source fixtures.

Begin provider authorization

Outcome

Before you start

Discover the target

Request

Input fields

Effects

Interpret the response

Worked examples

Refused request · HTTP 502

Successful request

Refused request · HTTP 503

Refused request · HTTP 403

Another supported response

Refused request · HTTP 401

Refused request · HTTP 404

Another supported response

Refused request · HTTP 403

Another supported response

Refused request · HTTP 403

Refused request · HTTP 502

Another supported response

Refused request · HTTP 503

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence