Connection

Before you can publish, each destination social account must be connected to your workspace. You can do that in the dashboard, or programmatically so your own product can send users through OAuth and land them back on your app.

Two ways to connect

Both paths use the same platform OAuth apps. After a successful connection, we send the browser to either the dashboard or your redirect_url.

Your app / dashboard
  → GET /v1/connections/oauth/{platform}/start
  ← { "url": "…" }

User authorizes on the platform
Onepostly saves the connection
  → redirect_url?connected=x&connectionId=…&handle=…

Dashboard

1. Open Connections in the app.
2. Pick a platform under Platforms and finish OAuth.
3. Copy the connection ID (copy button on each row), or list via API.

No redirect_url needed. Session cookie auth is enough.

Facebook: after Meta consent, the user picks one Page on Onepostly’s hosted select screen. Each connect adds a single Page connection.

Programmatic connect (API)

Use this when your users connect their X / Instagram / Facebook / Threads / LinkedIn / YouTube accounts inside your product.

1. Start OAuth

Requires a read_write API key. redirect_url is required for API-key starts.

curl "https://api.onepostly.com/v1/connections/oauth/x/start?redirect_url=https%3A%2F%2Fyourapp.com%2Foauth%2Fonepostly" \
  -H "x-api-key: op_YOUR_KEY"

{
  "url": "https://x.com/i/oauth2/authorize?…"
}

Open url in the browser (full page or popup). Platforms: x, instagram, facebook, threads, linkedin, youtube, tiktok, pinterest, reddit.

redirect_url rules:

• Absolute URL
• https required (exception: http://localhost, 127.0.0.1, *.lvh.me for local dev)

Optional: reconnect=<connectionId> to re-authorize an existing connection without consuming a plan slot.

Optional (Facebook only): headless=true — see Facebook page selection below.

2. Handle the return

On success we redirect to your URL with query params:

On failure:

Example success:

https://yourapp.com/oauth/onepostly?connected=x&connectionId=…&handle=%40you&count=1

3. List connections anytime

curl https://api.onepostly.com/v1/connections \
  -H "x-api-key: op_YOUR_KEY"

{
  "connections": [
    {
      "id": "YOUR_CONNECTION_ID",
      "platform": "x",
      "handle": "@you",
      "displayName": "…",
      "status": "active",
      "canAutoRenew": true,
      "authHealth": "healthy"
    }
  ]
}

read_only keys can list connections; starting OAuth needs read_write.

Facebook page selection

Facebook requires a secondary step after Meta OAuth: the user selects one Page. That Page becomes one connection. Connect again to add another Page.

Hosted (default)

Omit headless (or set it false). After Meta consent, Onepostly opens the hosted picker at /connections/facebook/select. When the user picks a Page, the browser is sent to your redirect_url (API) or the dashboard Connections page (session) with the usual success params.

curl "https://api.onepostly.com/v1/connections/oauth/facebook/start?redirect_url=https%3A%2F%2Fyourapp.com%2Foauth%2Fonepostly" \
  -H "x-api-key: op_YOUR_KEY"

Headless

Pass headless=true (requires redirect_url). After Meta consent, Onepostly redirects immediately to your redirect_url with:

Then your backend (or app) lists Pages and completes the select:

# List Pages
curl "https://api.onepostly.com/v1/connections/oauth/facebook/pages?tempToken=TEMP_TOKEN" \
  -H "x-api-key: op_YOUR_KEY"

# Select one Page
curl -X POST "https://api.onepostly.com/v1/connections/oauth/facebook/select" \
  -H "x-api-key: op_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tempToken": "TEMP_TOKEN",
    "pageId": "PAGE_ID",
    "redirect_url": "https://yourapp.com/oauth/onepostly/done"
  }'

{
  "connection": { "id": "…", "platform": "facebook", "displayName": "…" },
  "redirect_url": "https://yourapp.com/oauth/onepostly/done?connected=facebook&connectionId=…&count=1"
}

Redirect the browser to redirect_url. tempToken alone is enough to authorize list/select (no session required); if you also send a session or API key, it must belong to the same organization.

Reconnect of an existing Facebook connection skips the picker and re-binds the same Page id.

Errors

Next: Quickstart · Authentication · OpenAPI