Connect Social Account API
The Connect Social Account API initiates an OAuth flow to connect a social media account. Use it to generate a platform authorization URL, optionally bind the resulting integration to a profile or a custom OAuth app, redirect the user to authorize, and then continue with the stored connection. Bluesky follows a separate Bluesky app password flow instead of an OAuth redirect.
Connect Social Account API overview and task
The Connect Social Account API starts an OAuth flow for a single social platform. Your backend calls the endpoint with a platform value, receives an authorization URL, and redirects the user to that URL. After the user authorizes on the platform, the callback handles the token exchange and stores the connection. If redirectUri was supplied, the user is redirected there after a successful connection. Creating a profile beforehand is optional, yet tying the outcome to a profile helps your backend pinpoint the newly created integration: store the returned profile.id, send it as profileId, then query integrations filtered by that profileId. Omitting a profile leaves the connection flow unchanged.
Endpoint and path parameters
The endpoint is GET {{API_BASE_URL}}/v1/connect/{platform}. The platform path parameter is a required string and must be one of twitter, youtube, tiktok, facebook, instagram, pinterest, linkedin, threads, or googlebusiness. Before redirecting the user, check that platform is present and matches one of those exact values; an unsupported value cannot produce a valid OAuth URL for this endpoint. A practical request builder therefore confirms the platform enum, adds only the optional query parameters you intend to use, sends the request with your access key header, and verifies the response contains a url field before assigning it as the redirect target.
Query parameters and Instagram login method
Three optional query parameters shape the authorization step. redirectUri is an optional string holding the destination for the user after a successful connection. profileId is an optional string that associates the resulting integration with a profile, so later lookups can isolate the integration created in this flow by querying /v1/connect/integrations?profileId=... . appId is an optional string for using your own OAuth app: set that app up through the BYOK setup guide, create it via /v1/apps/, and supply the returned app.id in this parameter. Instagram behaves differently by default, using Direct Instagram Login. Setting loginMethod=facebook_login instead routes a professional Instagram account through its linked Facebook Page, unlocking Instagram catalog-audio search and Reel audio publishing. The Instagram platform guide covers prerequisites, account choice, capability checks, and reconnect handling.
Example requests and response
The examples below show a plain Twitter request and a second variant adding redirectUri. Both use the exact GET path with the platform in the path and the access key in the x-access-key header. The response carries a single url field pointing to the platform authorization page. Send the user to that url, or launch it in a separate browser tab. Once authorization finishes on the platform, the callback exchanges the token and stores the connection encrypted, and a supplied redirectUri sends the user back to your app.
How It Works sequence
The sequence runs as follows: your app requests GET /v1/connect/{platform} and receives an OAuth URL; you send the user to that URL or launch it in a separate browser tab; the user grants authorization on the platform, such as Twitter or YouTube; the platform returns the user to the callback; the callback swaps the code for tokens and stores them encrypted; and, when redirectUri was set, the user returns to your app. Use each stage as a check: without a returned url, do not redirect; without completed authorization, do not assume a stored connection exists; and without redirectUri, do not expect a return redirect to your app.
Bluesky app password flow
Bluesky does not use OAuth redirects, so it is not connected through the GET endpoint above. The end user generates an app password at the Bluesky app password settings page and submits it once through the separate POST endpoint shown below. The request body uses identifier, which is the user's handle or DID, and password, which must be an app password rather than the account password. A successful response carries the integration object; thereafter, integration.id serves as accountId when posting. The Bluesky platform docs give fuller detail. Keep the two paths distinct in your builder: Bluesky needs identifier and password, while the other platforms use the OAuth URL flow with platform plus optional redirectUri, profileId, appId, or loginMethod.
Status codes and failure handling
Handle the documented status codes explicitly. A 200 response means an OAuth URL was generated, so proceed to redirect the user to the returned url. A 403 response means the platform is not available, so stop and surface that the requested platform cannot be connected. A 500 response means platform credentials are not configured, so treat it as a configuration failure rather than retrying the same request unchanged. For Bluesky, apply the same discipline to the separate POST flow: only treat the connection as established when the response includes the integration object, and use integration.id as accountId thereafter.
| Parameter | Type | Description |
|---|---|---|
| platform | string | Platform to connect: "twitter", "youtube", "tiktok", "facebook", "instagram", "pinterest", "linkedin", "threads", or "googlebusiness" |
Exact source contract; origin modularized as {{API_BASE_URL}}.
| Parameter | Type | Required | Description |
|---|---|---|---|
| redirectUri | string | No | URL to redirect the user to after successful connection |
| profileId | string | No | Bind the resulting integration to a profile. Afterwards, list /v1/connect/integrations?profileId=... to find the integration created for that profile. |
| appId | string | No | Connect through your own OAuth app. Create the app with /v1/apps/ following the BYOK setup guide, then pass the returned app.id here. |
Exact source contract; all listed parameters are optional. loginMethod is documented in Instagram prose, not in this source table.
| Field | Prose-derived type | Required in practice | Description |
|---|---|---|---|
| identifier | string | Yes | The user's handle or DID, for example alice.bsky.social |
| password | string | Yes | An app password, not the account password, for example xxxx-xxxx-xxxx-xxxx |
Prose-derived field map for POST /v1/connect/bluesky/auth; source states semantics in prose without a typed schema table.
| Code | Meaning |
|---|---|
| 200 | OAuth URL generated |
| 403 | Platform not available |
| 500 | Platform credentials not configured |
Exact source status contract.
GET {{API_BASE_URL}}/v1/connect/{platform}curl "{{API_BASE_URL}}/v1/connect/twitter" \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/connect/twitter?redirectUri=https://yourapp.com/connected" \
-H "x-access-key: YOUR_API_KEY"{
"url": "https://twitter.com/i/oauth2/authorize?response_type=code&client_id=..."
}curl -X POST {{API_BASE_URL}}/v1/connect/bluesky/auth \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"identifier": "alice.bsky.social",
"password": "xxxx-xxxx-xxxx-xxxx"
}'