Connections with the TypeScript SDK ​

Connections are the social accounts linked to a workspace. Each has a stable slug such as instagram-mybrand, and you pass slugs in the connections array when you publish. The SDK manages connections through socifyr.workspaces.

How do I list my connection slugs? ​

const connections = await socifyr.workspaces.listConnections(workspaceId)

for (const c of connections) {
  console.log(c.slug, c.platform, c.status, c.expiresAt)
}
// instagram-mybrand instagram active 2026-12-20T09:00:00.000Z
// x-myhandle x expiring 2026-11-15T09:00:00.000Z

listConnections(workspaceId) takes the workspace ID as an argument. It does not default to the client's workspaceId.

The Connection type:

needs_reconnect means only a reconnect link can fix the connection. See connection concepts for how status is computed.

How do I refresh an expiring connection? ​

const result = await socifyr.workspaces.refreshConnection(workspaceId, 'x-myhandle')
console.log(result.status, result.expiresAt, result.lastRefreshedAt)

ConnectionRefreshResult: id, slug, platform, expiresAt, lastRefreshedAt, status, canRefresh.

Refresh needs a stored refresh token and a platform adapter that supports it. Otherwise the API answers 400 with a message such as No refresh token available. Please reconnect instead. The SDK throws ValidationError. Fall back to a reconnect link.

How do I reconnect an expired account? ​

const link = await socifyr.workspaces.getReconnectLink('x-myhandle')
console.log(link.url, link.expiresIn) // https://api.socifyr.com/... 600

ReconnectLink has url, expiresIn (seconds), platform and slug. The link is single-use and short-lived. Send it to the account owner. After they authorize, the same connection and slug are updated in place, so scheduled posts keep working.

This calls POST /oauth/connections/:ref/reconnect-link.

How do I check and fix expiring accounts in one script? ​

const connections = await socifyr.workspaces.listConnections(workspaceId)

for (const c of connections) {
  if (c.status === 'active') continue
  if (c.canRefresh) {
    await socifyr.workspaces.refreshConnection(workspaceId, c.slug)
  } else {
    const link = await socifyr.workspaces.getReconnectLink(c.slug)
    console.log(`Reconnect ${c.slug}: ${link.url}`)
  }
}

How do I switch the Facebook page a connection posts to? ​

await socifyr.workspaces.updateConnectionTarget(workspaceId, connectionId, {
  targetId: '17841400012345678',
  targetName: 'My Brand Page',
})

To post to a second page under the same login, fork the connection:

const raw = await socifyr.workspaces.forkConnection(workspaceId, connectionId, {
  targetId: '1004860882719628',
  targetName: 'Second Page',
})

forkConnection returns the raw connection document. Call listConnections afterwards to get the new slug.

How do I disconnect an account? ​

FAQ ​

Can the SDK start an OAuth connection? ​

No. There is no SDK method to create a new connection. Connect accounts in the dashboard and use the SDK for everything after that.

Which role do I need? ​

Refresh requires the platform-connect permission in the workspace. The Python SDK has refresh_connection and reconnect_link too. See Python workspaces.

Next steps ​

• Connection concepts
• Workspaces resource
• Publish a post