Outcome
Store a supplied provider token in Nexus and return Flow 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.
- Authorize the documented mutation effects before CLI --confirm or MCP confirm:true. Fixture credentials and ids authorize no live operation.
Discover the target
topolo whoami --json
topolo actions get app_topolo_flow.connections.create --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
POST /api/connections
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} |
label | Optional | Optional display label for the Nexus connection. | {} |
token | Required | Authorized provider access token supplied through protected credential handling; never commit a live token or reuse the synthetic fixture token. | {"minLength":1} |
scope | Optional | Optional provider scope metadata; supplying it does not establish provider eligibility or broader permissions. | {} |
View the full input schema through the action reference or CLI/MCP discovery.
Effects
- Normalizes the provider, creates a fresh connection id and sends credentials to Nexus. Repeated calls create distinct ids; tokens are not returned by the Flow projection. Scope is organization-wide across Flow workspaces.
- 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
Read $.connection.id for the returned connection identifier. An empty collection does not discover a target.
Read connections.list and match the returned id/provider/status. Fixture storage is simulated and is not proof of live encrypted custody or provider eligibility.
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.
Successful request
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: connections.create.
Input · payload.json:
{
"provider": "fixture",
"label": "Fixture provider",
"token": "synthetic-provider-token"
}
CLI:
topolo actions validate app_topolo_flow.connections.create --data @payload.json --json
topolo actions plan app_topolo_flow.connections.create --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.connections.create --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --confirm --detail --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_flow.connections.create",
"input": {
"provider": "fixture",
"label": "Fixture provider",
"token": "synthetic-provider-token"
},
"resourceType": "workspace",
"resourceId": "<id returned by granted resource discovery>",
"confirm": true
}
}
Captured local response · HTTP 201:
{
"connection": {
"id": "flw_eba0af50a3e048419aed",
"provider": "fixture",
"displayName": "Fixture provider",
"username": null,
"status": "active",
"scope": null,
"kind": "api_key",
"tokenExpiresAt": null,
"createdAt": "2026-10-05T00:00:00Z"
}
}
HTTP 201. Read connections.list and match the returned id/provider/status. Fixture storage is simulated and is not proof of live encrypted custody or provider eligibility.
Refused request · HTTP 403
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: read workspace grant refused.
Input · payload.json:
{
"provider": "fixture",
"token": "synthetic-provider-token"
}
CLI:
topolo actions validate app_topolo_flow.connections.create --data @payload.json --json
topolo actions plan app_topolo_flow.connections.create --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.
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: Nexus unavailable.
Input · payload.json:
{
"provider": "fixture",
"token": "synthetic-provider-token"
}
CLI:
topolo actions validate app_topolo_flow.connections.create --data @payload.json --json
topolo actions plan app_topolo_flow.connections.create --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
Captured local response · HTTP 502:
{
"error": "synthetic_nexus_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.
Refused request · HTTP 403
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: read_write workspace grant refused.
Input · payload.json:
{
"provider": "fixture",
"token": "synthetic-provider-token"
}
CLI:
topolo actions validate app_topolo_flow.connections.create --data @payload.json --json
topolo actions plan app_topolo_flow.connections.create --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.
Refused request · HTTP 401
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: anonymous action.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_flow.connections.create --data @payload.json --json
topolo actions plan app_topolo_flow.connections.create --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.
Verify the result
- Read connections.list and match the returned id/provider/status. Fixture storage is simulated and is not proof of live encrypted custody or provider eligibility.
Errors and recovery
synthetic_nexus_unavailable(HTTP 502): After an uncertain write discover the returned/existing connection metadata before retrying. Disconnect the exact created connection only when separately authorized; do not guess ids.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.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
After an uncertain write discover the returned/existing connection metadata before retrying. Disconnect the exact created connection only when separately authorized; do not guess ids.
Related actions
- List Flow connections: Read organization-wide provider connection metadata owned by Nexus for Flow.
- Disconnect a provider: Remove the exact organization-scoped Nexus connection available to 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.