Manage app connections
FLOWRA_MANAGE_CONNECTIONSConnect the user to an app, or check whether an app is already connected. Pass the toolkit slugs you need; connections are per end user and several toolkits can be checked in one call.
mode:
"connect" (default): if not already active, start the normal connect flow (may return redirectUrl / requires_parameters).
"status": read-only. Never mint OAuth/consent links or create INITIATED rows. Returns active / not_connected / no_auth_required / needs_setup only.
Each toolkit comes back with a status you must handle:
active / no_auth_required: ready — go execute the app's tools.
not_connected: only when mode is "status" — no active connection; call again with mode "connect" (or omit mode) when the user wants to connect.
initiated: redirectUrl is set. Show that one markdown link and stop. Do not call this tool again until the user says they finished connecting in the browser. Then call with the same toolkits to confirm it is active. A verify call must not mint a second link (wasReinitiated stays false).
requires_parameters: the user must supply credentials. Ask for exactly the fields listed in requiredParameters, showing each field's description, then call again with specifyCustomAuth.
requires_challenge: only when this status is returned. Ask for exactly the fields in requiredParameters, then call again with challengeResponse: { connectionId, plus those field names }. Do not invent a verification step when this status is absent.
needs_setup: a secondary end user cannot connect yet because project App credentials are missing. Tell them the app is not ready; never ask them for client_id, client_secret, or other app-level secrets. (Project default / owner instead gets requires_parameters for those App credential fields.)
failed: read errorMessage before retrying.
When talking to the user, use the label field (email, username, or app name). Never show a connection UUID.
Use specifyCustomAuth to activate an API key, bearer token, basic auth, or pasted cookies directly, without opening a browser. Pass session.id from FLOWRA_DISCOVER_TOOLS when you are continuing the same discovery session.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | connect (default): may start OAuth/consent when not active. status: read-only check — never mint redirectUrl or INITIATED rows. | connect |
| session | No | Optional meta session.id from DISCOVER for correlation (not required for OAuth). | |
| toolkits | Yes | List of toolkit slugs (base like 'gmail' or project-scoped like 'gmail:abc123') to check or connect. Prefer base slugs from CREATE_OR_UPDATE_TOOLKIT / DISCOVER_TOOLS — project suffix is resolved automatically. Never invent slugs. | |
| reinitiateAll | Yes | Force reconnection for ALL toolkits in the `toolkits` list, even if they already have active connections. DEFAULT: false (preserve existing active connections). Ignored when mode is status. | |
| challengeResponse | No | Continue a pending challenge only after status is requires_challenge. Pass connectionId plus the field names from requiredParameters. Do not send this unless that status was returned. | |
| specifyCustomAuth | No | Agent-friendly way to provide per-toolkit credentials and connection fields. Outer object: keys are toolkit names (must match entries in `toolkits`). Inner object: credentials for that toolkit. Supported patterns: API Key {"apiKey": "YOUR_KEY"}, Bearer Token {"bearerToken": "YOUR_TOKEN"}, Basic Auth {"username": "USER", "password": "PASS"}, Cookie {"cookies": "..."}, email/password {"email":"...","password":"..."}, Custom OAuth {"client_id": "...", "client_secret": "..."}, plus any field names from the toolkit authConfigDetails. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| error | No | Error if any occurred during the execution of the action | |
| message | No | ||
| successful | No | Whether or not the action execution was successful or not |