How to connect, refresh and reconnect social accounts ​

New accounts are connected in the dashboard. After that, every surface can list connections, read each one's status (active, expiring or needs_reconnect), renew a token with refresh, and request a one-time reconnect link when only the account owner can fix it. You never need the dashboard again for an expired token.

Background on slugs and statuses: Connections and slugs.

How do I connect a new account? ​

Open Accounts in the dashboard and click Connect next to a platform. OAuth platforms send you to the platform's consent screen. Bluesky, Telegram, Discord, Mastodon, Nostr, Slack, Dev.to, Hashnode and Tumblr use a short credential form instead (an app password, token, webhook URL or API key). See Platforms. Only the workspace owner can connect accounts, and the number of accounts is capped by plan. See Connect accounts in the dashboard and limits.

No SDK, CLI, MCP or REST call starts a new connection. The API exposes only reconnect links for accounts that already exist.

How do I list connections and see their status? ​

Sidebar > Accounts. Each account shows its health and a Reconnect or
Refresh token action when it needs attention.

socifyr connections
socifyr connections --json | jq '.[] | {slug, status, canRefresh, expiresAt}'

const connections = await socifyr.workspaces.listConnections('ws_123')
for (const c of connections) {
  console.log(c.slug, c.platform, c.status, c.canRefresh)
}

for c in client.workspaces.list_connections("ws_123"):
    print(c["slug"], c["platform"], c.get("status"), c.get("canRefresh"))

curl https://api.socifyr.com/api/workspaces/ws_123/connections \
  -H "Authorization: Bearer $SOCIFYR_API_KEY" \
  -H "X-Workspace-Id: ws_123"

{ "tool": "list_connections", "arguments": {} }

Response (trimmed):

{
  "success": true,
  "data": [
    {
      "id": "65f3a1b2c3d4e5f6a7b8c9d0",
      "slug": "linkedin-myhandle",
      "platform": "linkedin",
      "platformUsername": "myhandle",
      "targetName": null,
      "expiresAt": "2026-12-18T10:00:00.000Z",
      "lastRefreshedAt": null,
      "hasRefreshToken": true,
      "status": "expiring",
      "canRefresh": true
    }
  ]
}

The MCP tool prints one line per account and flags the ones that need action, for example ⚠ NEEDS RECONNECT — call reconnect_connection.

How do I refresh an expiring account? ​

Refresh renews the token with the stored refresh token. The owner does not have to do anything. It works only when canRefresh is true.

socifyr connections refresh linkedin-myhandle

const r = await socifyr.workspaces.refreshConnection('ws_123', 'linkedin-myhandle')
console.log(r.status, r.expiresAt)

r = client.workspaces.refresh_connection("ws_123", "linkedin-myhandle")
print(r["status"])

curl -X POST https://api.socifyr.com/api/workspaces/ws_123/connections/linkedin-myhandle/refresh \
  -H "Authorization: Bearer $SOCIFYR_API_KEY" \
  -H "X-Workspace-Id: ws_123"

{ "tool": "refresh_connection", "arguments": { "connection": "linkedin-myhandle" } }

Response:

{
  "success": true,
  "data": {
    "id": "65f3a1b2c3d4e5f6a7b8c9d0",
    "slug": "linkedin-myhandle",
    "platform": "linkedin",
    "expiresAt": "2027-02-16T10:00:00.000Z",
    "lastRefreshedAt": "2026-12-18T10:05:00.000Z",
    "status": "active",
    "canRefresh": true
  }
}

The dashboard equivalent is Refresh token on the account card.

How do I reconnect an expired account? ​

When status is needs_reconnect, or a post failed with reconnect_required, request a reconnect link. The owner opens it in a browser and approves the same account.

socifyr connections reconnect x-myhandle

const link = await socifyr.workspaces.getReconnectLink('x-myhandle')
console.log(link.url, link.expiresIn) // expiresIn is in seconds

link = client.workspaces.reconnect_link("x-myhandle")
print(link["url"])

curl -X POST https://api.socifyr.com/api/oauth/connections/x-myhandle/reconnect-link \
  -H "Authorization: Bearer $SOCIFYR_API_KEY" \
  -H "X-Workspace-Id: $SOCIFYR_WORKSPACE_ID"

{ "tool": "reconnect_connection", "arguments": { "connection": "x-myhandle" } }

Response:

{
  "success": true,
  "data": {
    "url": "https://api.socifyr.com/api/oauth/x/connect-popup?code=...",
    "expiresIn": 600,
    "platform": "x",
    "slug": "x-myhandle"
  }
}

• The link is single use and expires in 10 minutes.
• Approving the same account updates the connection in place. The slug and scheduled posts keep working. Approving a different account creates a new connection.
• Open the link yourself. Chat apps that preview links can consume a single-use link.
• Only the workspace owner can request one. Keys with guardrails cannot.

After approval, run retry on the failed post.

Prompt for your agent: "My X post failed. Fix the connection and retry it." The agent calls check_post_status, then refresh_connection. If that fails, it calls reconnect_connection, hands you the URL, waits for you to approve it, then calls retry_post.

What errors can I get, and how do I fix them? ​

FAQ ​

How often do tokens expire? ​

It varies by platform, often 60 to 90 days. Socifyr tracks expiresAt, warns by email 7 days ahead, and renews in the background when the platform issues a refresh token.

Does reconnecting change my slug? ​

No, if you approve the same account.

Next steps ​

• Reconnect an expired account in the dashboard
• Check status and retry failures
• REST reference: connections
• CLI: socifyr connections