Accounts
Start connecting an account
Starts a connect session.
POST
/v1/connect/{platform}TL;DR
| Question | Answer |
|---|---|
| What does it do? | Start connecting an account. |
| What does it need? | An API key, an OAuth access token, or a connect token (this is one of the calls a connect token may make). |
| What does it take? | A JSON body with the fields below, and platform in the path. |
| What does it return? | Status 201 with a body of type ConnectSession. |
| In the SDK? | flung.accounts.connect() |
| As an MCP tool? | connect_account |
| What can go wrong? | 401 Missing, unknown, revoked or expired API key; 422 The request failed validation; 429 Too many requests for this credential; wait for retry-after seconds. Every failure has the same error shape. |
What it does
Starts a connect session. Send the person to its authorizationUrl, the platform's consent page. When they finish, Flung stores the account and sends them to redirectUrl, or shows its own page when there is none; poll GET /v1/connect-sessions/{id} or listen for account.connected. Facebook connects one account per page the person can post to.
Example
bash
curl -X POST 'https://api.flung.dev/v1/connect/linkedin' \ --header "Authorization: Bearer $FLUNG_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: $(uuidgen)" \ --data '{ "redirectUrl": "https://app.example.com/settings/social", "handle": "alice.bsky.social"}'ts
import { Flung } from '@flung.dev/sdk'
const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })const result = await flung.accounts.connect({ platform: 'linkedin', redirectUrl: 'https://app.example.com/settings/social', handle: 'alice.bsky.social',})js
const response = await fetch('https://api.flung.dev/v1/connect/linkedin', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.FLUNG_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ redirectUrl: 'https://app.example.com/settings/social', handle: 'alice.bsky.social', }),})if (!response.ok) throw new Error((await response.json()).error.message)const result = await response.json()A successful answer looks like this:
json
{ "id": "cs_aaaaaaaaaaaaaaaaaaaaaaaa", "platform": "x", "accountId": "string", "status": "pending", "authorizationUrl": "https://example.com", "expiresAt": "2026-11-01T09:00:00.000Z", "accountIds": [ "string" ], "error": { "code": "string", "message": "string" }, "createdAt": "2026-11-01T09:00:00.000Z", "completedAt": "2026-11-01T09:00:00.000Z"}Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
platform | string | yes |
Request body
The body has the type an object, with the fields below.
| Field | Type | Required | Description |
|---|---|---|---|
redirectUrl | string | no | Where Flung sends the person when the flow ends, with flung_session_id, flung_status (connected or error), and flung_account_ids or flung_error in the query. Omit it and Flung shows its own "you can close this tab" page; poll the session instead. at most 2048 characters. |
profileId | string | no | The profile the connected accounts belong to. |
handle | string | no | Bluesky: the handle signing in, such as alice.bsky.social (omit to sign in through bsky.social). Mastodon: the instance, such as mastodon.social or @you@mastodon.social (required). at least 3 characters; at most 253 characters. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The session is ready. | ConnectSession |
| 401 | Missing, unknown, revoked or expired API key. | Error |
| 422 | The request failed validation. | Error |
| 429 | Too many requests for this credential; wait for retry-after seconds. | Error |
Response body
A 201 answer has the type ConnectSession.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
platform | Platform | yes | |
accountId | string | null | yes | The account being reconnected; null for a new connection. |
status | "pending" | "connected" | "failed" | "expired" | yes | pending until the person finishes on the platform; expired when they did not by expiresAt. |
authorizationUrl | string | null | yes | Send the person here: the platform's own consent page. Null once the session has ended. |
expiresAt | string | yes | The person must finish by then. |
accountIds | string[] | yes | The accounts stored, once connected. Facebook connects one per page. |
error | object | null | yes | Why it failed: access_denied, wrong_account, platform_error and so on. |
error.code | string | yes | |
error.message | string | yes | |
createdAt | string | yes | |
completedAt | string | null | yes |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint |
| Schemas | Every request and response type |
| Errors | Every error code and what to do about it |
connect_account | The same operation as an MCP tool |