Start Connection

The Connect API starts the OAuth flow for a platform and binds the resulting accounts to a profile. Use it to let your own users connect their social accounts without leaving your product.

The flow has three steps:

1. GET /v1/connect/:platform returns an auth_url. Redirect the user there.
2. The user authorizes on the platform and is redirected back to your redirect_url.
3. For platforms with multiple targets (e.g. Facebook Pages), resolve the pending grant to persist the chosen accounts.

Query parameters

curl "https://api.socialit.com/v1/connect/x?profile_id=pro_9aB...&redirect_url=https://yourapp.com/done" \
  -H "Authorization: Bearer sk_live_..."

{ "auth_url": "https://twitter.com/i/oauth2/authorize?...", "state": "..." }

After the user authorizes, they are redirected to your redirect_url with either:

• ?connected=x&account_id=sa_... — a single account was connected, or
• ?grant=<grant_id>&platform=x — multiple targets need selection (see Resolve Grant), or
• ?error=<code> — the connection failed.

Credential Connection

Some platforms (e.g. Bluesky) connect with a username and app password instead of a redirect.

curl -X POST https://api.socialit.com/v1/connect/bluesky \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "pro_9aB...", "identifier": "you.bsky.social", "password": "app-password" }'

{ "connected": ["sa_..."] }

Get Grant

Lists the accounts discovered during OAuth so the user can pick which to connect.

curl https://api.socialit.com/v1/connect/grants/GRANT_ID \
  -H "Authorization: Bearer sk_live_..."

{
  "platform": "meta",
  "targets": [
    { "external_id": "123", "account_type": "page", "name": "Acme Page", "username": null, "avatar_url": "https://..." }
  ]
}

Resolve Grant

Persists the selected targets, assigned to the grant’s profile.

Body parameters

curl -X POST https://api.socialit.com/v1/connect/grants/GRANT_ID \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_ids": ["123"] }'

{ "connected": ["sa_..."] }