Start OAuth Flow (Step 1 of 3)
OAuth Connection Flow - Step 1: Initiate OAuth
This is the first step in the 3-step OAuth flow to connect a social media account:
- Start OAuth (this endpoint) → User authenticates with the platform
- Get Accounts → Retrieve available pages/channels to connect
- Attach Account → Connect the selected account to your location
How to Use
Open this API in a browser window (not via cURL) with the required query parameters. The user will be redirected to the platform's OAuth login screen.
Receiving the OAuth Response
After successful authentication, the OAuth window will post a message back to your application. Listen for this message to get the accountId needed for the next step.
window.addEventListener('message', function(e) {
if (e.data && e.data.page === 'social_media_posting') {
const { actionType, page, platform, placement, accountId, reconnectAccounts } = e.data;
// Use accountId for Step 2: GET /oauth/{locationId}/{platform}/accounts/{accountId}
}
}, false);
Event Data Response
| Field | Type | Example | Description |
|---|---|---|---|
| actionType | string | "close" | The action type |
| page | string | "social-media-posting" | Source page identifier |
| platform | string | "facebook" | The OAuth platform |
| placement | string | "placement" | Placement context |
| accountId | string | "658a9b6833b91e0ecb8f3958" | Use this for Step 2 |
| reconnectAccounts | string[] | ["658a9b...", "efd2da..."] | Accounts that need reconnection |
Next Step
Use the accountId from the response to call:
GET /social-media-posting/oauth/{locationId}/{platform}/accounts/{accountId}
Platform Notes
- bluesky: Currently not supported, will return an error
- tiktok-business: Uses a separate business OAuth flow
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your access token.
socialplanner/ oauth. readonlyOAuthPrivate IntegrationSub-Account TokenRequest
Headers
API Version
v3v3Path Parameters
Social media platform to connect. Each platform has specific account types:
- google: Google Business Profile locations
- facebook: Facebook Pages
- instagram: Instagram Professional Accounts (Business/Creator)
- linkedin: LinkedIn Pages and Profiles
- tiktok: TikTok Creator Accounts
- tiktok-business: TikTok Business Center Accounts
- youtube: YouTube Channels
- pinterest: Pinterest Business Accounts
- threads: Threads Profiles
- bluesky: Bluesky Accounts (currently not supported)
googleQuery Parameters
Location Id
w37swmmLbA02zgqKPpxITe2User Id
u37swmmLbA02zgqKPpxITe2Page
integrationReconnect
trueInstagram only. Selects which Instagram connection flow to run. Ignored by every other platform.
instagram— Direct Instagram Login: the user signs in with their Instagram credentials on instagram.com and no Facebook Page is required.facebook— Instagram via Facebook: the user signs in with Facebook and the Instagram account must be linked to a Page they manage.
Omitted defaults to the Facebook flow, so loginType=instagram must be sent explicitly to offer Direct Instagram Login.
facebookinstagraminstagramApp URL to redirect back to after OAuth finishes, for the same-tab (mobile) flow. When present and the host is trusted for the location, the finish page 302-redirects here with platform/accountId/error query params instead of using the popup postMessage handshake.
https://staging.socialplanner.clientclub.net/sp-e/connect-accountResponse
Redirect to the platform OAuth consent screen