Connect Sessions
Create hosted account-connection flows for end users. Connect Sessions can use UniPost's shared OAuth apps or workspace platform credentials, depending on credential availability and allow_quickstart_creds.
When to use Connect Sessions
Use Connect Sessions when your product needs to send an end user through account authorization and then publish on behalf of the account they connected. Use POST/v1/oauth/connect when you are connecting accounts owned by your own workspace team.
| Question | Answer |
|---|---|
| Primary API | POST/v1/connect/sessions |
| Who authorizes | Your end user, inside UniPost's hosted Connect flow |
| What you store | external_user_id plus the completed managed_account_id |
| What you publish with | managed_account_id, used as the UniPost account_id in platform_posts |
| Credential modes | Shared UniPost OAuth app or workspace platform credentials |
| Session lifetime | 30 minutes. Polling after the TTL returns expired for sessions still pending. |
| Plan gates | Some platforms can require a paid plan before account connection. For example, X / Twitter may return 402 PLAN_PLATFORM_NOT_ALLOWED. |
Credential sources
The endpoint is the same in both modes. The difference is which OAuth app the platform sees during authorization. If you omit allow_quickstart_creds, it defaults to false, so OAuth platforms require uploaded workspace Platform Credentials.
| Source | How to create it | OAuth app used | Best for |
|---|---|---|---|
| Shared UniPost OAuth app | allow_quickstart_creds=true | Workspace credentials if present; otherwise UniPost's shared OAuth app | Customer onboarding where shared OAuth app fallback is acceptable |
| Workspace platform credentials | allow_quickstart_creds=false and uploaded platform credentials | Your platform app credentials stored in UniPost | Customer onboarding where the platform consent screen must show your app |
If a workspace has platform credentials for the requested platform, UniPost uses those credentials. allow_quickstart_creds=trueonly permits fallback to UniPost's shared app when workspace credentials are missing.
On Basic, workspace Platform Credentials are active only for the workspace's shared custom platform slot. Growth, Team, and Enterprise can use workspace Platform Credentials across all supported OAuth platforms.
These credential modes apply to OAuth platforms. Bluesky uses app passwords instead of OAuth apps, so allow_quickstart_creds does not change the Bluesky Connect Session path.
Shared-app fallback session
Pass allow_quickstart_creds=true when you want hosted customer onboarding without requiring workspace-owned Platform Credentials first.
Workspace-credential session
Upload workspace Platform Credentials first, then create sessions with allow_quickstart_creds=falseso missing credentials fail immediately instead of silently falling back to UniPost's shared app.
Callback URL vs return_url
These names are easy to mix up, but they control different redirects.
| Field or URL | Who controls it | Purpose |
|---|---|---|
return_url | Your integration | Where UniPost sends the browser after the Connect Session finishes or fails. |
| OAuth callback URL / redirect URI | UniPost and the platform developer console | Where the social platform sends the OAuth code. Shared-app fallback users do not configure this; workspace credential users copy the exact platform callback URL into their developer app. |
For workspace Platform Credentials, copy callback URLs from the platform guides under Platform Credentials. Do not replace them with your return_url.
Handle completion
The hosted URL is browser-facing. Your backend should subscribe to the account.connected webhook and store the returned social_account_id as the account id for future publishing. This is the recommended production path because UniPost pushes the result as soon as the account is connected.
See Developer webhooks for subscription setup, signatures, and retry behavior.
Poll as a fallback
Poll GET/v1/connect/sessions/:session_id for local development, CLI demos, or integrations that cannot receive webhooks. Stop polling on every terminal state: completed, expired, or cancelled. A pending session expires after 30 minutes.
Cloudflare Workers and Wrangler
If you call Connect Sessions from Cloudflare Workers or local wrangler dev and see an error like internal error; reference = ..., the request may be failing inside the workerd runtime before it reaches UniPost. In that environment, configure the SDK with UniPost's DNS-only origin API endpoint. Keep using https://api.unipost.dev everywhere else.
No cache clearing is normally required. If the error persists after switching baseUrl, restart wrangler dev once so workerd picks up the new hostname resolution.