Guide
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.
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
- Get an authorization URL.
GET /v1/connect/linkedin?profile_id=pro_…&redirect_url=https://your-app.com/connectedreturns{ "object": "connect_url", "url", "state", "expires_at" }. - Send the user to
url. The network redirects to Socialit, which exchanges the code. - The user lands on your
redirect_urlwith?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.
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).
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:
GET /v1/connect/pending-data?token=…returns the targets the user can pick (Pages, organizations, locations, boards…).- Render your picker.
POST /v1/connect/selectwith{ "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).