Create an account connect session

Creates a short-lived browser handoff session for an agent-assisted account connection. Open connect_session.connect_url in the user browser. The dashboard will ask the user to log in if needed, start the selected provider flow, then update the session status as the user progresses. Poll connect_session.poll_url until the status is connected, failed, cancelled, or expired.

post/api/v1/connect/{platform}/sessions

Request

Base URL: https://www.poster.ly
URL: https://www.poster.ly/api/v1/connect/{platform}/sessions
Auth: HTTP bearer

Path parameters

platformstring required

Connection target, for example instagram, meta, linkedin_page, twitter, google_business, telegram, or bluesky.

Request body

workspace_idstring uuid

Optional workspace to connect the account into. Workspace-scoped API keys ignore this and use their bound workspace.

auto_startboolean

When true, the dashboard starts the selected provider flow after the user opens the connect URL.

Response

Connect session created successfully

Example response

{
  "connect_session": {
    "id": "8ec5ae8c-fd6b-4e0b-83d7-0f88c3f5e9e1",
    "platform": "instagram",
    "method": "dashboard_oauth",
    "status": "awaiting_provider",
    "status_message": "User is approving the provider OAuth connection.",
    "connect_url": "https://www.poster.ly/dashboard/connect?platform=instagram&connect_session=8ec5ae8c-fd6b-4e0b-83d7-0f88c3f5e9e1&auto_start=1",
    "poll_url": "https://www.poster.ly/api/v1/connect/sessions/8ec5ae8c-fd6b-4e0b-83d7-0f88c3f5e9e1",
    "workspace_id": "2d0a6d4c-9eef-4ee2-9026-2ca0dc29c8d6",
    "connected_account_ids": [],
    "connected_accounts": [],
    "connected_count": 0,
    "error_code": null,
    "error_message": null,
    "created_at": "2026-05-19T10:00:00.000Z",
    "opened_at": "2026-05-19T10:00:12.000Z",
    "provider_redirected_at": "2026-05-19T10:00:18.000Z",
    "completed_at": null,
    "expires_at": "2026-05-19T10:30:00.000Z"
  },
  "connect": {
    "platform": "instagram",
    "aliases": [
      "instagram-standalone",
      "instagram_direct"
    ],
    "label": "Instagram",
    "status": "supported",
    "method": "dashboard_oauth",
    "provider_platforms": [
      "instagram"
    ],
    "dashboard_url": "https://www.poster.ly/dashboard/connect?platform=instagram",
    "connection_url": "https://www.poster.ly/dashboard/connect?platform=instagram",
    "oauth_url": null,
    "supports_direct_oauth_url": false,
    "supports_direct_credentials": false,
    "credentials_endpoint": null,
    "requires_browser_session": true,
    "configured": true,
    "env_requirements": [
      {
        "any_of": [
          "NEXT_PUBLIC_INSTAGRAM_APP_ID"
        ],
        "description": "Instagram OAuth app ID"
      }
    ],
    "missing_env": [],
    "scopes": [
      "instagram_business_basic",
      "instagram_business_manage_messages",
      "instagram_business_manage_comments",
      "instagram_business_content_publish",
      "instagram_business_manage_insights"
    ],
    "credential_fields": [],
    "notes": [
      "Starts the direct Instagram login flow from the posterly dashboard.",
      "Use this for Instagram publishing, native media tags, caption mentions, inbox, comments, and analytics.",
      "Collaborator invitations require an eligible Meta-linked Instagram connection.",
      "Use connection_url in a logged-in browser, or create a connect session with POST /api/v1/connect/{platform}/sessions for pollable agent progress. Direct public OAuth URL generation is intentionally not exposed because provider callbacks depend on short-lived browser state."
    ],
    "connected_count": 1,
    "connected_accounts": [
      {
        "id": "123",
        "platform": "instagram",
        "username": "thebrightlabuae",
        "account_type": "profile",
        "connection_mode": "instagram_direct"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.