Connect Sessions
Connect sessions are the hosted onboarding layer for customer-owned social accounts. They let your app create a session, redirect an end user into UniPost's hosted flow, and receive a managed social account when the flow completes.
When to use Connect sessions
Use Connect sessions when you are building a product where your customers connect their own end-user-owned social accounts. This is how UniPost becomes account-onboarding infrastructure rather than just a direct posting API.
Flow
| Step | What happens |
|---|---|
| Create session | Your backend creates a session and receives a hosted URL |
| User completes hosted flow | UniPost handles OAuth or Bluesky credential collection |
| Managed account is created | UniPost stores and refreshes the resulting social account |
| Webhook or poll | Your app learns the flow completed and can start publishing |
Create a session
Create a connect session with the platform, your own stable end-user identifier, and a return URL. The resulting URL is what you send or redirect your user to.
curl -X POST https://api.unipost.dev/v1/connect/sessions \
-H "Authorization: Bearer up_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"platform": "twitter",
"external_user_id": "user_123",
"external_user_email": "alice@acme.com",
"return_url": "https://app.acme.com/integrations/done"
}'Important fields
| Field | Required | Notes |
|---|---|---|
| platform | ✓ | Currently used to choose the hosted flow and downstream platform semantics |
| external_user_id | ✓ | Your stable identifier for the end user |
| external_user_email | X | Helpful for your own reconciliation and support workflows |
| return_url | Recommended | Where UniPost redirects the user after completion |
Read session status
Polling is available for development and simple integrations. In production, the recommended path is to listen for the account-connected webhook and then look up the resulting account.
curl https://api.unipost.dev/v1/connect/sessions/cs_abc123 \
-H "Authorization: Bearer up_live_xxxx"Status model
| Status | Meaning |
|---|---|
| pending | The user has not completed the hosted flow yet |
| completed | The session produced a managed social account |
| expired | The hosted flow was not completed before expiration |