Connecting Accounts

OmniPost publishes on behalf of your end users' social accounts. Connecting one is a single API call plus a hosted redirect — OmniPost handles the platform's OAuth dance, token storage, and refresh.

The connect flow

Call POST /v1/accounts/:platform/connect from your backend to get a hosted URL, then redirect your end user (the person whose Instagram, TikTok, X, or Threads account you want to publish to) to it.

curl -X POST https://api.omnipost.dev/v1/accounts/tiktok/connect \
  -H "Authorization: Bearer $OMNIPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://yourapp.com/settings/social" }'

{
  "url": "https://www.tiktok.com/v2/auth/authorize/?client_id=...&redirect_uri=...&state=..."
}

What the redirect does

1. url is the platform's own OAuth consent screen (e.g. tiktok.com/v2/auth/authorize) — OmniPost doesn't interpose a branded page for live connections, so send your end user there directly.
2. Its state parameter is an opaque, single-use connection attempt id tied to your workspace; it expires after 10 minutes if unused.
3. On approval, the platform redirects back to OmniPost's callback, which exchanges the authorization code for tokens and stores them encrypted, associated with your workspace.
4. OmniPost then redirects the end user to your redirect_url (or a generic confirmation page if omitted).
5. The new account now appears in GET /v1/accounts with status: active.

Sandbox mock-connect behavior

When the request is authenticated with an op_sandbox_ key, the returned urlpoints to a mock connect screen instead of the real platform. No real OAuth exchange happens — clicking "Connect" immediately creates a fake account (realistic username, avatar, and platform-shaped ID) with status: active in your workspace. This is what makes it possible to exercise the entire connect → publish → webhook lifecycle without waiting on Meta, TikTok, or X app review.

Token refresh is automatic

Instagram, Threads, and TikTok all issue short-lived access tokens with a longer-lived refresh token; X issues a 2-hour access token with a rotating refresh token. OmniPost tracks each token's expiry and refreshes it automatically in the background, well before it expires. You never call a refresh endpoint yourself.

When a token expires or is revoked

If a refresh fails — most commonly because the end user revoked access from the platform's own settings, changed their password, or the platform-side grant simply expired — OmniPost marks the account accordingly rather than silently dropping it.

Poll GET /v1/accountsperiodically, or check the status returned inline whenever you fetch a post's targets, to detect this before a publish attempt fails.

Disconnecting an account

curl -X DELETE https://api.omnipost.dev/v1/accounts/acct_ig_5f8b2c9a1d7e4f30 \
  -H "Authorization: Bearer $OMNIPOST_API_KEY"

Disconnecting revokes OmniPost's stored tokens for that account and removes it from future publish targets. It does not delete posts already published through it, and it does not revoke the grant on the platform's side beyond what the platform's own token-invalidation API performs on disconnect.

A note on connect notifications

The connect flow itself completes via the browser redirect described above — that's the "callback." OmniPost's webhook events today cover post lifecycle only (post.completed, post.failed). If you need to react to an account transitioning to expired or revoked outside of a publish attempt, poll GET /v1/accounts on a schedule until an account.* webhook event ships.

Required scopes

The exact OAuth scopes OmniPost requests are documented per platform, since they differ:

• Instagram — instagram_business_basic, instagram_business_content_publish.
• Threads — threads_basic, threads_content_publish.
• TikTok — video.publish.
• X — tweet.read, tweet.write, users.read, offline.access.