Appearance

Connections and slugs ​

A connection is an OAuth link to one social account: an Instagram business page, a LinkedIn profile, an X handle, a Facebook page, etc.

Every connection has a stable, human-readable slug like:

  • instagram-mybrand
  • linkedin-myhandle
  • x-myhandle
  • facebook-mypage
  • tiktok-me
  • bluesky-myhandle-bsky-social
  • youtube-mychannel
  • pinterest-mypin
  • reddit-myhandle
  • threads-myhandle

The slug is generated when you first connect the account and never changes (even if you revoke and reconnect — it's keyed by the platform user ID). Always use slugs in your code, never platform names or raw ObjectIds.

Listing connections ​

typescript
const connections = await socifyr.workspaces.listConnections(workspaceId)
for (const c of connections) {
  console.log(`${c.slug}  →  ${c.platform} (${c.targetName})`)
}
bash
socifyr connections
bash
curl -H "Authorization: Bearer sk_..." \
     -H "X-Workspace-Id: <workspaceId>" \
     https://api.socifyr.com/api/workspaces/<workspaceId>/connections

Connecting a new account ​

Connections are made via OAuth in the web dashboard — there is no programmatic way to start an OAuth flow from the SDK. Visit Settings → Integrations in the dashboard, click the platform, and authorize.

Supported platforms ​

PlatformPhotoVideoTextCarouselStoryReelsDocument
Instagram✓✓—✓✓✓—
Facebook✓✓✓✓✓✓—
LinkedIn✓✓✓✓——✓
X (Twitter)✓✓✓✓———
TikTok—✓———✓—
YouTube—✓———✓—
Threads✓✓✓✓———
Bluesky✓✓✓✓———
Pinterest✓✓—————
Reddit✓✓✓————

For exact character limits, supported aspect ratios, and platform-specific quirks, see platform-constraints.ts in packages/shared.

Token expiry ​

OAuth tokens expire (typically 60–90 days, varies by platform). Socifyr:

  1. Tracks expiresAt for every connection
  2. Sends an email warning 7 days before expiry
  3. Renews tokens in the background (and once more on an auth error while publishing) when the platform issues a refresh token
  4. Reports a status on every connection: active, expiring, or needs_reconnect
  5. Fails publishes that hit a dead token with a reconnect_required error that names the slug and the fix

Reconnecting without the dashboard ​

You never have to leave your agent or script to fix an expired account:

SurfaceRenew silently (if the platform allows)Re-authorize (owner opens a link)
MCPrefresh_connectionreconnect_connection
CLIsocifyr connections refresh <slug>socifyr connections reconnect <slug>
SDKworkspaces.refreshConnection(workspaceId, slug)workspaces.getReconnectLink(slug)
RESTPOST /api/workspaces/:id/connections/:slug/refreshPOST /api/oauth/connections/:slug/reconnect-link

The reconnect link is short-lived (10 minutes) and single-use, contains no access token, and updates the existing connection in place when the owner approves the same account (approving a different account creates a new connection), so the slug and any scheduled posts keep working. Open it yourself rather than pasting it into chat apps: link-preview bots can use up a single-use link. Only the workspace owner can approve it; keys with guardrails (daily limits, approval required) cannot mint one. The dashboard Reconnect button still works too.

Disconnecting ​

typescript
// Remove from your workspace (keeps platform access intact)
await socifyr.workspaces.disconnectPlatform(workspaceId, connectionId)

// Revoke the OAuth token AND remove from your workspace
await socifyr.workspaces.revokePlatform(workspaceId, connectionId)