Skip to content
Docs

Guide

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.

Updated Oct 14, 2026

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 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 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.

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).

Terminal
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).