> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postbreeze.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

1. You POST with the `workspaceId` and `platform` you want to connect.
2. The server returns an `authorizeUrl` — open it in a browser (redirect your user there, or open it yourself).
3. The user logs in on the platform and approves the requested permissions.
4. 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.



## OpenAPI

````yaml /openapi.json post /social-accounts/connect
openapi: 3.0.0
info:
  title: Postbreeze API
  description: >-
    Public REST API for scheduling and managing social posts. Authenticate every
    request with `Authorization: Bearer pb_live_…`. All endpoints are scoped to
    a single workspace; an API key issued for workspace A cannot access
    workspace B.
  version: 1.0.0
  contact: {}
servers:
  - url: http://localhost:4100/api/v1
security:
  - bearer: []
tags: []
paths:
  /social-accounts/connect:
    post:
      tags:
        - Channels
      summary: Start an OAuth connect flow
      description: >-
        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:


        1. You POST with the `workspaceId` and `platform` you want to connect.

        2. The server returns an `authorizeUrl` — open it in a browser (redirect
        your user there, or open it yourself).

        3. The user logs in on the platform and approves the requested
        permissions.

        4. 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.
      operationId: SocialAccountsV1Controller_connect
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectChannelDto'
      responses:
        '201':
          description: Authorization URL minted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  authorizeUrl:
                    type: string
                    description: >-
                      URL the user must open to grant permissions. Single-use;
                      expires with the OAuth state.
                  state:
                    type: string
                    description: >-
                      Opaque random string echoed by the OAuth callback. Surface
                      it in your UI if you need to disambiguate concurrent
                      connect attempts.
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 400
                  code:
                    type: string
                    example: VALIDATION_FAILED
                  message:
                    type: string
                  requestId:
                    type: string
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: Unauthorized
                  requestId:
                    type: string
        '409':
          description: >-
            The workspace already has an account connected for this platform.
            Disconnect it first, or use a different workspace.
components:
  schemas:
    ConnectChannelDto:
      type: object
      properties:
        workspaceId:
          type: string
          description: Workspace that should own the connected account.
          example: ws_01HZX5T2K9Q3RB6N6JZP3RYV0M
        platform:
          type: string
          enum:
            - INSTAGRAM
            - FACEBOOK_PAGE
            - X
            - LINKEDIN_PERSON
            - LINKEDIN_COMPANY
            - TIKTOK_BUSINESS
            - TIKTOK_PERSONAL
            - YOUTUBE
            - PINTEREST
            - THREADS
            - BLUESKY
          description: >-
            Which platform to start the OAuth flow for. Reuse the `platform`
            value returned by `GET /social-accounts` rows.
          example: INSTAGRAM
      required:
        - workspaceId
        - platform
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: Your Postbreeze API key

````