Skip to main content
OAuth | GenericVersion: v3

Start OAuth Flow (Step 1 of 3)

GET/social-media-posting/oauth/{platform}/start

OAuth Connection Flow - Step 1: Initiate OAuth​

This is the first step in the 3-step OAuth flow to connect a social media account:

  1. Start OAuth (this endpoint) → User authenticates with the platform
  2. Get Accounts → Retrieve available pages/channels to connect
  3. 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​

FieldTypeExampleDescription
actionTypestring"close"The action type
pagestring"social-media-posting"Source page identifier
platformstring"facebook"The OAuth platform
placementstring"placement"Placement context
accountIdstring"658a9b6833b91e0ecb8f3958"Use this for Step 2
reconnectAccountsstring[]["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

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:socialplanner/oauth.readonly
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version

Available optionsv3
Example:v3

Path Parameters

platformstringrequired

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)
Example:google

Query Parameters

locationIdstringrequired

Location Id

Example:w37swmmLbA02zgqKPpxITe2
userIdstringrequired

User Id

Example:u37swmmLbA02zgqKPpxITe2
pagestring

Page

Example:integration
reconnectstring

Reconnect

Example:true
loginTypestring

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

Available optionsfacebookinstagram
Example:instagram
returnUrlstring

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

Example:https://staging.socialplanner.clientclub.net/sp-e/connect-account

Response

Redirect to the platform OAuth consent screen