Connect end-user apps

Choose app access

Open Embedded > Embedded API > Setup in MindCloud. Turn on Allow users to connect any app via API to connect apps without preparing an integration first. MindCloud Embedded must also be enabled for your company.

The switch starts off. Enabling it creates no integrations or installations. MindCloud prepares an integration when you request a connection link for an app. Existing integrations and SDK connection flows remain available.

The MCP server has its own switch under Embedded > Home. Each switch controls its own connection links. Turning API catalog access off limits new REST links to configured single-app connect integrations. Create an integration or confirm an older integration in its Setup tab to configure it for API access. Apps connected through catalog access do not become configured integrations automatically. Embedded API remains available, and users can still connect configured apps. Existing accounts remain available for reads and action runs while Embedded is enabled.

Identify the user

Create an end user through POST /v1/users and save the returned MindCloud userId on your server. Use that ID as endUserId below. Bind it to the signed-in user in your application before each request. Keep your MindCloud API key on your server.

An API key can address end users only in its own company. Admin keys cannot use X-Company-Id to change this company scope.

Create a connection link

Find an app slug or ID through GET /v2/universal/apps. Request a link with a full_access API key:

curl -X POST \
  "https://connect.mindcloud.co/v2/embedded/end-users/$END_USER_ID/connect-links" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"appRef":"slack"}'

The response is 201 Created:

{
  "success": true,
  "data": {
    "url": "https://app.mindcloud.co/embedded-install#t=<token>&channel=api",
    "appName": "Slack",
    "expiresAt": "2026-10-01T12:15:00.000Z",
    "singleUse": true
  }
}

Show the returned URL only to this end user. Whoever opens it can connect an account as that end user. Use the URL exactly as returned, including its fragment. The link lasts fifteen minutes and works once. Each end user can request ten REST links per minute.

The hosted page opens the Embedded connection flow. Its thirty-minute session has the existing scope for that end user and installation. For repair, that installation can include the other apps in its existing integration. If a failure occurs after the link is consumed, request a new link.

List connected accounts

Use a read_only API key or a higher access level:

curl \
  "https://connect.mindcloud.co/v2/embedded/end-users/$END_USER_ID/connections?limit=20&offset=0" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

{
  "success": true,
  "data": [
    {
      "connectionId": "Cn6vH3jW8qYt",
      "appSlug": "slack",
      "appName": "Slack",
      "label": "Support workspace",
      "status": "valid",
      "connectedOn": "2026-10-01T12:05:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "totalCount": 1,
      "totalCountExact": true,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}

The page limit is 1–100, with a default of 20. The offset starts at zero. The list includes existing SDK and MCP accounts owned by this end user. It contains public IDs and account information only.

Run an action

Use a run_workflows API key or a higher access level. Add endUserId to the existing Universal action request. Pass the selected public connectionId when the user has several usable accounts:

curl -X POST \
  "https://connect.mindcloud.co/v2/universal/apps/slack/actions/send-channel-message/run" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "enduser_GhSUEYhipn4g",
    "connectionId": "Cn6vH3jW8qYt",
    "arguments": {"channel":"C123","text":"Hello"}
  }'

The API uses only this end user's connected accounts. It accepts the exact public connection ID from the list. It does not accept labels, internal credential IDs, or default as a REST connection ID. Without an ID, it selects the sole usable account. Several usable accounts return 409 CONNECTION_CHOICE_REQUIRED with public choices. Select an account and retry with its ID.

REST action execution requires a connected account, including apps without authentication. The existing installationId request remains supported. Use it separately from connectionId.

Resolve lookup choices

Use the same endUserId and selected account for provider lookups:

curl \
  "https://connect.mindcloud.co/v2/universal/apps/slack/actions/send-channel-message/lookups/channel?endUserId=$END_USER_ID&connectionId=$CONNECTION_ID&q=support" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

This prevents dropdown choices from using a company account. End-user ownership is checked for fixed choices too.

Repair an account

Request a new connection link with its public ID:

{
  "appRef": "slack",
  "connectionId": "Cn6vH3jW8qYt"
}

For an SDK account, repair keeps its installation and integration settings and updates that account. For a provisioned account without an installation, the SDK creates a new account and keeps the original credential. After authentication, reload the connection list and use the new account's public connectionId. The original ID still selects the provisioned credential.

Handle failures