Connect a social account

Initiates account connection. For OAuth2 platforms returns an auth_url to redirect the user to. For apikey/credentials platforms stores the credentials immediately and returns account_id.

POST /accounts/connect

Connect a social account

cURL

curl --request POST \
  --url https://api.social-api.ai/v1/accounts/connect \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "brand_id": "b_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "metadata": {},
  "platform": "instagram",
  "redirect_uri": "https://app.acme.com/oauth/done",
  "state": "session_abc123"
}
'

201

{
  "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "display_name": "Acme Corp",
  "platform": "instagram",
  "username": "acmecorp"
}

Authorizations

Authorization · string · header · required

Prefix your API key with "Bearer ". Example: Authorization: Bearer sapi_key_...

Body

application/json

Platform and metadata

brand_id · string

BrandID optionally specifies which brand to attach the account to. If omitted, a new brand is auto-created.

Example:

"b_01HZ9X3Q4R5M6N7P8V2K0W1J"

metadata · object

Metadata contains platform-specific connection data

Show child attributes

platform · string

Platform identifies the social platform to connect (e.g. instagram, facebook, google, threads, tiktok, linkedin).

Example:

"instagram"

redirect_uri · string

RedirectURI is the customer's URL to redirect the user to after OAuth completes. Must be pre-registered in the dashboard whitelist. If omitted, the default HTML success page is shown.

Example:

"https://app.acme.com/oauth/done"

state · string

CustomerState is an opaque value echoed back to the customer's redirect URI. Max 512 chars.

Example:

"session_abc123"

Response

201

application/json

Account connected (direct auth)

account_id · string

Example:

"acc_01HZ9X3Q4R5M6N7P8V2K0W1J"

display_name · string

Example:

"Acme Corp"

platform · string

Example:

"instagram"

username · string

Example:

"acmecorp"