Channels

Start an OAuth connect flow

Starts the process of connecting a social account (Instagram, TikTok, LinkedIn, etc.) to one of your workspaces.

Connecting an account requires the account owner to log in on the platform’s website and approve Postbreeze — something only a real browser can do. This endpoint kicks that off:

You POST with the workspaceId and platform you want to connect.
The server returns an authorizeUrl — open it in a browser (redirect your user there, or open it yourself).
The user logs in on the platform and approves the requested permissions.
The platform redirects back to Postbreeze and the new account appears in GET /social-accounts for that workspace.

The authorizeUrl is single-use and expires after a few minutes, so open it right away. The state value is just a random string you can use to match this connect attempt to the user who started it — Postbreeze validates it server-side on the callback.

One account per platform per workspace. If the workspace already has an account connected for the same platform, this endpoint returns 409 CHANNEL_ALREADY_CONNECTED before opening OAuth. To connect a different account for the same platform, create a separate workspace.

Only workspace owners and admins can start a connect flow.

POST

social-accounts

connect

Start an OAuth connect flow

curl --request POST \
  --url http://localhost:4100/api/v1/social-accounts/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "workspaceId": "ws_01HZX5T2K9Q3RB6N6JZP3RYV0M",
  "platform": "INSTAGRAM"
}
'

{
  "authorizeUrl": "<string>",
  "state": "<string>"
}

Authorizations

Authorization

string

header

required

Your Postbreeze API key

Body

application/json

workspaceId

string

required

Workspace that should own the connected account.

Example:

"ws_01HZX5T2K9Q3RB6N6JZP3RYV0M"

platform

enum<string>

required

Which platform to start the OAuth flow for. Reuse the platform value returned by GET /social-accounts rows.

Available options:

INSTAGRAM,

FACEBOOK_PAGE,

X,

LINKEDIN_PERSON,

LINKEDIN_COMPANY,

TIKTOK_BUSINESS,

TIKTOK_PERSONAL,

YOUTUBE,

PINTEREST,

THREADS,

BLUESKY

Example:

"INSTAGRAM"

Response

Authorization URL minted.

authorizeUrl

string

URL the user must open to grant permissions. Single-use; expires with the OAuth state.

state

string

Opaque random string echoed by the OAuth callback. Surface it in your UI if you need to disambiguate concurrent connect attempts.

Get a connected channelReturns a single connected social account. You don't need to pass the workspace — Postbreeze figures it out from the account itself. You just need to be a member of the workspace that owns the account.

Start an OAuth connect flow

curl --request POST \
  --url http://localhost:4100/api/v1/social-accounts/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "workspaceId": "ws_01HZX5T2K9Q3RB6N6JZP3RYV0M",
  "platform": "INSTAGRAM"
}
'

{
  "authorizeUrl": "<string>",
  "state": "<string>"
}