Custom UI Flow

Use custom UI when you want full control over account connection screens. You generate an OAuth URL, redirect the user, handle the callback, fetch the saved social account, and call channel endpoints when a platform needs a selected target. Endpoint: POST /api/v1/social-account/connect Test it in Swagger or the API Reference Client.

{
  "type": "INSTAGRAM",
  "teamId": "team_123",
  "redirectUrl": "https://app.example.com/oauth/callback",
  "instagramConnectionMethod": "FACEBOOK",
  "disableAutoLogin": true,
  "withBusinessScope": true
}

Response:

{
  "url": "https://www.facebook.com/v..."
}

Redirect the user to url.

Connect Body

These are the available body fields for the custom flow.

Field	Required	Description
`type`	Yes	Platform to connect. See Supported Types.
`teamId`	Yes	Team that should receive the connected social account.
`redirectUrl`	Yes	HTTP/HTTPS URL where the platform sends the user after OAuth. We append callback query parameters to this URL.
`serverUrl`	Depends	Required for Mastodon. Optional issuer/server URL for Bluesky.
`disableAutoLogin`	No	Adds provider-specific flags to avoid automatic login or silent account reuse where supported. Defaults to `false`.
`tiktokForceLogin`	No	Experimental TikTok-only option. Routes authorization through TikTok logout to request a fresh login session. Defaults to `false`.
`forceBrowserOAuth`	No	Instagram direct OAuth only. Forces browser OAuth on phones where possible. Defaults to `false`.
`instagramConnectionMethod`	No	Instagram only. Use `FACEBOOK` or `INSTAGRAM`. If omitted, the Facebook login path is used.
`withBusinessScope`	No	Facebook and Instagram via Facebook only. Adds broader Meta business scopes when `true`. Defaults to `false`.

Supported Types

TIKTOK, YOUTUBE, SNAPCHAT, INSTAGRAM, FACEBOOK, TWITTER, THREADS, LINKEDIN, PINTEREST, REDDIT, MASTODON, DISCORD, SLACK, BLUESKY, GOOGLE_BUSINESS

Platform-Specific Options

Option	Applies to	Notes
`serverUrl`	Mastodon, Bluesky	Mastodon requires it. Bluesky can use it for a custom issuer/server.
`instagramConnectionMethod: "FACEBOOK"`	Instagram	Uses Facebook Login and supports Page/account channel selection, comments, insights, locations, and Instagram audio search.
`instagramConnectionMethod: "INSTAGRAM"`	Instagram	Uses direct Instagram OAuth. No `set-channel`, `unset-channel`, or `refresh-channels`. Some Facebook-backed features are not available.
`disableAutoLogin`	Facebook, Instagram via Facebook, Instagram direct OAuth, TikTok	Helps users pick the correct platform account when many accounts are used in one browser.
`tiktokForceLogin`	TikTok	Experimental stronger fresh-login flow. Redirects through TikTok logout before authorization.
`forceBrowserOAuth`	Instagram direct OAuth	Avoids the Instagram iOS app deep-link path when possible.
`withBusinessScope`	Facebook, Instagram via Facebook	Can expose Pages and Instagram accounts that are hidden in the standard Meta scope flow.

For Facebook and Instagram via Facebook, ask users to select all Pages and Instagram accounts they manage in Meta OAuth. Then call set-channel for the one target this team should use.

Basic Flow

Call POST /api/v1/social-account/connect.
Redirect the user to the returned url.
Handle the callback query parameters on your redirectUrl.
Fetch the social account with GET /api/v1/social-account/by-type.
If socialAccount.channels contains selectable targets, show them in your UI.
Call POST /api/v1/social-account/set-channel when required.

Snapchat connects the Public Profile returned by OAuth and does not need channel selection.

Fetch The Connected Account

Use this after the callback to inspect the connection and available channels. Endpoint: GET /api/v1/social-account/by-type Query:

Field	Required	Description
`type`	Yes	Platform type.
`teamId`	Yes	Team ID.

GET /api/v1/social-account/by-type?type=FACEBOOK&teamId=team_123

If the platform needs channel selection, read socialAccount.channels and call Set Channel.

Helper Endpoints

These endpoints are useful in a full custom UI.

Endpoint	Method	Use
`/api/v1/social-account/disconnect`	`DELETE`	Disconnect a social account from the team. This also removes it from scheduled posts.
`/api/v1/social-account/set-channel`	`POST`	Select a Page, channel, organization, or location after OAuth.
`/api/v1/social-account/unset-channel`	`POST`	Clear the selected channel while keeping the OAuth connection.
`/api/v1/social-account/refresh-channels`	`POST`	Refresh available targets saved in `socialAccount.channels`.
`/api/v1/social-account/connection-check`	`POST`	Manually check whether a connected account is still valid. Requires a selected channel/account where the platform needs one.
`/api/v1/social-account/profile-refresh`	`POST`	Manually refresh profile information for a connected social account.
`/api/v1/social-account/by-type`	`GET`	Fetch the connected social account for a team and platform.

Channel details live in Channel Management. Callback query parameters live in Callback Parameters.

API Documentation

Platforms

Guides

Endpoints

Connect Body

Supported Types

Platform-Specific Options

Basic Flow

Fetch The Connected Account

Helper Endpoints

​Connect Body

​Supported Types

​Platform-Specific Options

​Basic Flow

​Fetch The Connected Account

​Helper Endpoints

Connect Body

Supported Types

Platform-Specific Options

Basic Flow

Fetch The Connected Account

Helper Endpoints