Connecting social accounts

Every post needs an accountId. Accounts are created when a human connects their social profile to a Postato workspace via OAuth. The API cannot connect accounts on its own; user consent is required by every platform.

User flow

From the dashboard's Accounts page:

1. User clicks Connect next to a platform (Instagram, Twitter/X, LinkedIn, TikTok, YouTube).
2. Browser redirects to the platform's OAuth authorization page.
3. User grants permission (usually scopes like tweet.read, tweet.write, users.read).
4. Platform redirects back to Postato with an authorization code.
5. Postato exchanges the code for access + refresh tokens, encrypts them at rest, and creates the social_accounts row.
6. The account appears in the workspace's account list.

End state: accountId (e.g. acc_01H...) is now usable in POST /posts and the publish_post MCP tool.

Supported platforms and scopes

If your use case needs additional scopes (e.g., reading insights, polling engagement), let us know; we evaluate case-by-case.

Token lifecycle

Postato stores access + refresh tokens encrypted with AES-256-GCM. Keys never leave the server; they are NEVER returned in any API response.

• Access tokens are short-lived (minutes to hours, platform-specific). Postato refreshes them automatically before expiry.
• Refresh tokens are long-lived (days to a year). Some platforms rotate the refresh token on every use; Postato handles that transparently.
• If refresh fails (user revoked access, password change, suspension), the account transitions to status: "token_expired" and future publishes fail with a clear error.

The user must reconnect. Postato cannot recover without a fresh OAuth flow.

Disconnecting

From the dashboard: user clicks Disconnect on the account card. Immediate.

From the API:

DELETE /v1/workspaces/{workspaceId}/accounts/{accountId}
Authorization: Bearer $API_KEY

This revokes tokens at the platform (where supported) and soft-deletes the account row. Historical posts referencing the account remain intact.

One user, many accounts

A single Postato user can connect multiple accounts of the same platform (e.g., two Twitter accounts across two different Twitter users). Each is a distinct accountId. The platform's OAuth flow handles user selection. If they're already logged in to the wrong account on the platform, have them log out there first.

Cross-workspace accounts

Accounts are workspace-scoped. The same Twitter handle can be connected independently in two workspaces, each with its own accountId. This is intentional: workspaces are isolation boundaries, and OAuth consent should be explicit per-workspace.

Developer note: no service accounts

There is no "headless" way to connect an account. Even for automation, a real user must complete the OAuth dance once. This is a platform requirement, not a Postato choice; the social networks don't expose programmatic credential issuance.