What does Socifyr do automatically?
- It tracks
expiresAton every connection. - It emails a warning 7 days before expiry.
- It renews tokens in the background, and once more on an auth error during publishing, when the platform issues a refresh token.
- It reports a
statuson every connection:active,expiringorneeds_reconnect. - If a publish still hits a dead token, it fails with a
reconnect_requirederror that names the slug and the fix.
The plain-language version of that failure reads "Instagram needs to be reconnected" with a hint that the connection expired or was revoked. It is not retried, because retrying a dead token cannot succeed.
How do I fix an expired account without opening the dashboard?
| Surface | Renew silently | Re-authorize (owner opens a link) |
|---|---|---|
| MCP | refresh_connection | reconnect_connection |
| CLI | socifyr connections refresh <slug> | socifyr connections reconnect <slug> |
| SDK | workspaces.refreshConnection(workspaceId, slug) | workspaces.getReconnectLink(slug) |
| REST | POST /api/workspaces/:id/connections/:slug/refresh | POST /api/oauth/connections/:slug/reconnect-link |
async function heal(slug: string) {
try {
const r = await socifyr.workspaces.refreshConnection(workspaceId, slug)
return { ok: true, status: r.status }
} catch {
// Could not refresh (Meta, LinkedIn, or a dead refresh token)
const link = await socifyr.workspaces.getReconnectLink(slug)
return { ok: false, reconnectUrl: link.url, expiresInSeconds: link.expiresIn }
}
}socifyr connections refresh instagram-mybrand
socifyr connections reconnect instagram-mybrandHow does the reconnect link work, and is it safe?
- It is single-use and expires after 10 minutes.
- It contains no access token. It carries a short-lived code that Socifyr redeems when the owner opens it.
- Only the workspace owner can approve it. API keys with guardrails (daily limits, approval required) cannot create one.
- If the owner approves the same account, the existing connection is updated in place, so the slug and any scheduled posts keep working. Approving a different account creates a new connection instead.
- Open the link yourself. Do not paste it into a chat app, because link-preview bots can fetch it and use up the single-use code.
For an AI agent, the flow is: the agent notices needs_reconnect in list_connections, calls reconnect_connection, and hands the link to you. You approve, then the agent retries the failed post with retry_post. The agent never needs the credentials. See how MCP servers let Claude post.
How do I stop expiry from breaking scheduled posts?
- Check
list_connectionsorsocifyr connectionsweekly and act on anythingexpiring. - Treat the 7-day warning email as a deadline for Meta and LinkedIn accounts, which cannot renew silently.
- Prefer long-lived credentials for internal channels: Telegram, Discord and Slack never expire.
- Because the reconnect keeps the slug, you do not need to touch scheduled posts after reconnecting.
- Subscribe to the
platform.failedwebhook event (Business plan) to trigger a reconnect workflow when a publish fails.
What should my code check when a post fails?
Treat auth failures differently from everything else. Retrying a dead token cannot succeed, while a timeout or rate limit often can. The decision table below mirrors how the error-handling guide classifies failures.
| Signal | Meaning | Action |
|---|---|---|
reconnect_required, or an error like Token has expired | The token is dead | refresh_connection, then the reconnect link |
Connection status is expiring | Expiry is near | Refresh now if the platform supports it, otherwise schedule a reconnect |
Connection status is needs_reconnect | Cannot refresh | Get a reconnect link for the owner |
429 or a rate limit message | Too fast | Back off and retry |
| A 400 validation error | Your request is wrong | Fix it, do not retry |
After the owner approves a reconnect, call retry on the failed post. Channels that already published are skipped, so the retry only affects the account that failed.
Frequently asked questions
How long do Instagram tokens last?
About 60 days for Meta long-lived tokens. They cannot be refreshed silently, so the owner reconnects through a one-time link.
Does refresh_connection work for Instagram?
No. Meta and LinkedIn require re-authentication, so use
reconnect_connection (MCP), socifyr connections reconnect (CLI) or getReconnectLink (SDK).Will reconnecting change my connection slug?
No. Approving the same account updates the connection in place, so the slug and scheduled posts are unchanged.
Who can approve a reconnect link?
Only the workspace owner. Keys with guardrails cannot create the link at all.
Do Telegram, Discord and Slack connections expire?
No. Bot tokens and webhooks last until revoked or deleted.