# PostEverywhere Account Connection Guide

> Connect social accounts from the API, an AI agent, or the terminal. Mint OAuth connect links for X, Instagram, Facebook, YouTube, Pinterest, Threads, LinkedIn, TikTok, or pass credentials directly for Telegram, Discord, Bluesky.

**Source:** https://posteverywhere.ai/docs/connecting-accounts
**Section:** Getting started
**API reference:** https://posteverywhere.ai/docs/api/reference

---

Everything else in this API assumes a connected social account. This page is how you get one **without touching the dashboard**: from a script, a CLI, or an AI agent (the MCP tools `create_connect_link`, `create_reconnect_link`, and `connect_credential_account` wrap these endpoints).

There are two connection styles, decided by the platform:

| Style | Platforms | Browser needed? |
| --- | --- | --- |
| OAuth connect link | `x`, `instagram`, `facebook`, `youtube`, `pinterest`, `threads`, `linkedin`, `tiktok` | One click by the account owner (the platform's own consent screen; that hop is imposed by the platforms, not us) |
| Direct credentials | `telegram`, `discord`, `bluesky` | None. Fully in-API |

## Connect an OAuth platform with a hosted link: `POST /v1/accounts/connect-link`
```bash
curl -X POST https://app.posteverywhere.ai/api/v1/accounts/connect-link \
  -H "Authorization: Bearer pe_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform": "instagram"}'
```

```json
{
  "data": {
    "platform": "instagram",
    "url": "https://www.instagram.com/oauth/authorize?...",
    "expires_in_seconds": 600,
    "instructions": "Have the instagram account owner open this URL in any browser within 10 minutes..."
  },
  "error": null
}
```

The flow, `gh auth login` style:

1. Mint the link (requires the `write` scope; expires in **10 minutes**).
2. Hand it to the account owner. They can open it in **any** browser; they do not need to be logged in to PostEverywhere there, since the link carries a signed, single-org grant of who initiated it.
3. They approve on the platform's consent screen.
4. The account lands in your organization. **Poll `GET /v1/accounts`** until the new account appears (typically seconds after approval), then post to it.

Security properties: the link is HMAC-signed and bound to your organization and workspace, expires after 10 minutes, and can only ever ADD an account to the organization that minted it. It grants the clicker nothing. Treat it like any invite link: send it to the account owner directly, not somewhere public.

## Connect a credential platform such as Telegram or Discord: `POST /v1/accounts/connect-credential`
No browser, validated live against the platform before saving:

```bash
# Telegram: bot from @BotFather, bot must be an ADMIN of the channel
curl -X POST .../v1/accounts/connect-credential \
  -H "Authorization: Bearer pe_live_..." -H "Content-Type: application/json" \
  -d '{"platform": "telegram", "bot_token": "123456:ABC...", "channel": "@mychannel"}'

# Discord: Server Settings > Integrations > Webhooks
  -d '{"platform": "discord", "webhook_url": "https://discord.com/api/webhooks/..."}'

# Bluesky: Settings > App Passwords (never the main account password)
  -d '{"platform": "bluesky", "handle": "me.bsky.social", "app_password": "xxxx-xxxx-xxxx-xxxx"}'
```

Bad credentials return a `4xx` with the platform's reason in `error.details` (`400` for Telegram, `401` for Discord and Bluesky, `409` if another organization already holds the account), so agents can self-correct. Re-submitting credentials for an already-connected account updates it in place: that is also how these platforms reconnect.

## Reconnect an account whose token expired: `POST /v1/accounts/{id}/reconnect`
When `GET /v1/accounts/{id}/health` reports `needs_reconnection` or `token_expired`, mint a repair link:

```bash
curl -X POST https://app.posteverywhere.ai/api/v1/accounts/1234/reconnect \
  -H "Authorization: Bearer pe_live_..."
```

Same mechanics as connect-link, with one rule: the owner must approve **while logged in to the platform as that same profile**. Matching is by the platform's account id: authorizing as a different profile connects a new account instead of repairing this one. Verify with the health endpoint afterwards.

## Connecting accounts from an AI agent
- `list_accounts` before and after is the confirmation loop: mint link, wait for the human, poll until the platform appears, then proceed to posting.
- A connect link that expires unclicked costs nothing; mint a fresh one.
- Connecting an account someone ELSE's PostEverywhere workspace already holds is blocked by an anti-hijack guard; the human will see an explanatory error and should contact support if they believe they own the account.

## Full account endpoint reference
Every connect flow, headless: [Create connect link](/docs/api/create-connect-link) · [Create reconnect link](/docs/api/create-reconnect-link) · [Connect credential account](/docs/api/connect-credential-account) · [Start social connect](/docs/api/start-social-connect) · [Poll social connect](/docs/api/poll-social-connect).

**Related:** [checking an account can post](/docs/account-health) · [test accounts](/docs/testing) · [Instagram API guide](/docs/platforms/instagram) · [Bluesky app-password connect](/docs/platforms/bluesky) · [the Discord guide](/docs/platforms/discord) · [the Telegram guide](/docs/platforms/telegram)