> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connected accounts

> OAuth connected accounts and link creation

## What are connected accounts?

**Connected accounts** are the result of a user (or your app) authorizing Flowra to use a third-party service on their behalf. For example: “John connected his Slack workspace” or “Sarah connected her Google account.” Each connection is stored as a **connected account** — it holds the OAuth tokens and metadata (which toolkit, which [auth config](/guides/auth-configs), optional label). When a workflow runs a tool that needs that service (e.g. “send a Slack message”), Flowra uses the right connected account so the action runs in John’s or Sarah’s context.

So: **auth config** = your app’s credentials (client ID/secret); **connected account** = one user’s (or one context’s) linked account after they’ve clicked “Connect” and completed OAuth.

### Example use cases

* **“Connect Slack” in your app** — Call `POST /connected_accounts/link` with the toolkit and auth config; you get a URL. Send the user to that URL; they sign in with Slack and approve. Flowra creates a connected account. You can then list accounts or pass that account ID when running workflows so the bot acts in that workspace.
* **Multi-user support bot** — Each customer connects their own Slack/Gmail. You store which connected account belongs to which customer. When that customer chats, you run the workflow with their connected account so messages go from their account.
* **List or revoke** — List connected accounts (filter by toolkit, status, user). Let users “disconnect” by calling delete on the connected account.

### How it works

1. You have an [auth config](/guides/auth-configs) for the provider (e.g. Slack).
2. You call **Create link** with that config (and optional metadata like label, external user id). The API returns a **URL**.
3. The user opens the URL, completes OAuth (login, consent). Flowra creates the **connected account** and redirects back to your app.
4. Use the connected account ID when running workflows or tools that need that connection. You can **list** and **get** accounts, and **delete** to revoke.

***

## API endpoints

### List connected accounts

**GET** `/api/v1/connected_accounts` returns paginated connected accounts with filters.

| Query parameter       | Description                                |
| --------------------- | ------------------------------------------ |
| `toolkitSlugs`        | Filter by toolkit slugs                    |
| `statuses`            | Filter by status (e.g. `ACTIVE`, `FAILED`) |
| `authConfigIds`       | Filter by auth config IDs                  |
| `connectedAccountIds` | Filter by connected account IDs            |
| `eUIDs`               | Filter by external user IDs                |
| `labels`              | Filter by labels                           |
| `orderBy`             | `createdAt` or `updatedAt`                 |
| `orderDirection`      | `asc` or `desc`                            |
| `cursor`, `limit`     | Pagination (default limit 10)              |

### Create link session

**POST** `/api/v1/connected_accounts/link` creates a new auth link session. Users open the returned URL to complete OAuth and connect their account. Request body: **CreateConnectedAccountLinkDto** (see [API reference](/api-reference)).

### Get and delete

* **GET** `/api/v1/connected_accounts/{id}` — Get one connected account by ID.
* **DELETE** `/api/v1/connected_accounts/{id}` — Remove the connected account.

## Related

* [Auth configs](/guides/auth-configs) — OAuth/API key configs used by toolkits.
* [Workflows](/guides/workflows) — Use connected accounts when running workflows with third-party tools.
* [API reference: connected\_accounts](/api-reference) — Full schemas.