# Connecting accounts

> Connect social accounts with OAuth from your app, hand your customers a white-label hosted connect link, or run the whole flow headless through the Connect API.

A connected **account** (`sa_…`) is one identity on one network: an Instagram account, a Facebook Page, a YouTube channel, a Google Business location, a Discord channel. Accounts belong to **profiles** (`pro_…`), which group them by brand or client and scope who can see them. **Account groups** (`grp_…`) are free-form sets of accounts you can target in one post.

Everything here is in the [Accounts](/docs/api-reference/accounts/) reference (MCP toolset `accounts`). Each connected account counts against your plan's account allowance; reconnects never do.

## Pick a method

| Method | Best for | Endpoints |
|---|---|---|
| **OAuth redirect** | Your app sends the user to the network and gets them back | `GET /v1/connect/{platform}` |
| **Hosted connect link** | Your customers connect on a branded Socialit page | `POST /v1/connect/links` |
| **Headless** | You render every screen, including asset pickers | `GET /v1/connect/{platform}?headless=true`, `/v1/connect/select` |
| **Credentials** | Networks without OAuth (Bluesky app passwords, Mastodon tokens) | `POST /v1/connect/{platform}/credentials` |

`GET /v1/connect/platforms` lists every network with its connect methods.

## OAuth redirect

1. **Get an authorization URL.** `GET /v1/connect/linkedin?profile_id=pro_…&redirect_url=https://your-app.com/connected` returns `{ "object": "connect_url", "url", "state", "expires_at" }`.
2. **Send the user to `url`.** The network redirects to Socialit, which exchanges the code.
3. **The user lands on your `redirect_url`** with `?connected=linkedin&account_ids=sa_…&profile_id=pro_…`, or with `?error=<code>&error_message=…` (`oauth_denied`, `invalid_state`, `no_targets`, `account_limit_reached`, …).

Useful query parameters:

| Parameter | Use |
|---|---|
| `profile_id` | Profile for the new accounts (default: the workspace default profile) |
| `scope_set` | `core` (default) or `focus`: request the extra scopes [Focus mode](/docs/focus-mode/) needs |
| `reconnect_account_id` | Refresh one account in place (keeps its profile, never counts against the allowance) |
| `instance` | Mastodon server, such as `mastodon.social` (required for Mastodon) |
| `login_method` | Instagram: `instagram_login` or `facebook_login` |

When a login has several assets (Facebook Pages, LinkedIn organizations, Google Business locations, Pinterest boards, YouTube channels…), Socialit shows its own picker before redirecting back.

## Hosted connect links (white label)

Send your customer one link. They see your name, logo and colors, pick networks, sign in and choose assets; the accounts land in the profile you chose. Requires the `hostedConnect` feature (Business and Enterprise).

```bash
curl -X POST https://api.socialit.com/v1/connect/links \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "pro_8Lq2Vx7Bn4Mc1Zr8Tw3Ys6Hd0Kp",
    "name": "Acme onboarding",
    "platforms": ["instagram", "facebook", "linkedin", "tiktok"],
    "branding": { "name": "Acme Agency", "logo_url": "https://acme.example/logo.png", "primary_color": "#1D4ED8" },
    "redirect_url": "https://your-app.com/settings/social",
    "expires_in": 604800,
    "max_uses": 1
  }'
```

The response has the link `url` (`https://api.socialit.com/hosted/connect/<token>`). At the end the browser goes to `redirect_url?account_ids=sa_1,sa_2&platform=…&profile_id=…`, or to a branded success page. List, inspect and revoke links with `GET /v1/connect/links` and `DELETE /v1/connect/links/{id}`. Listen for `account.connected` to know when accounts arrive.

## Headless

For a fully custom UI, add `headless=true`. Multi-asset networks then return to your `redirect_url` with `?pending_token=…&step=select_page&platform=facebook` instead of showing the Socialit picker:

1. `GET /v1/connect/pending-data?token=…` returns the targets the user can pick (Pages, organizations, locations, boards…).
2. Render your picker.
3. `POST /v1/connect/select` with `{ "token": "…", "target_ids": ["…"] }` connects them and returns the accounts.

Network-specific pickers with Zernio-compatible bodies also exist (`/v1/connect/facebook/select-page`, `/v1/connect/linkedin/select-organization`, `/v1/connect/googlebusiness/select-location`, …). Pending selections expire after 30 minutes.

If your app receives the OAuth `code` itself, complete the flow with `POST /v1/connect/{platform}` and `{ code, state }`.

### Networks without OAuth

| Network | How |
|---|---|
| Bluesky | `POST /v1/connect/bluesky/credentials` with the handle and an **app password** (or OAuth with `identifier`) |
| Discord | `POST /v1/connect/discord` with `guild_id` and `channel_ids` once the bot is in the server |

## Health, scopes and reconnecting

Socialit refreshes tokens in the background. `GET /v1/accounts/health` (or `/v1/accounts/{id}/health`) reports token state, granted scopes and what each account can do. An account whose access was revoked becomes `needs_reconnect` and emits `account.needs_reconnect`; send the user through `GET /v1/connect/{platform}?reconnect_account_id=sa_…` to fix it.

`PATCH /v1/accounts/{id}` renames an account or moves it to another profile. `DELETE /v1/accounts/{id}` disconnects it (`account.disconnected`).

---

Source: https://socialit.com/docs/connecting-accounts/
