Connect

Tip — bind to a profile first: creating a profile before this step is optional, but if you want your backend to know exactly which integration was just connected, create one and save the returned profile.id — then pass it as ?profileId= below. After OAuth completes, list /v1/connect/integrations?profileId=... and you get only that user's integration. Without a profile the connect flow still works exactly as before.

Endpoint

GET https://api.postpeer.dev/v1/connect/{platform}

Path Parameters

*More coming soon

Query Parameters

Example

curl "https://api.postpeer.dev/v1/connect/twitter" \
  -H "x-access-key: YOUR_API_KEY"

With redirect:

curl "https://api.postpeer.dev/v1/connect/twitter?redirectUri=https://yourapp.com/connected" \
  -H "x-access-key: YOUR_API_KEY"

Response

{
	"url": "https://twitter.com/i/oauth2/authorize?response_type=code&client_id=..."
}

Redirect the user to the returned url. After they authorize on the platform, PostPeer's callback handles the token exchange and stores the connection. If redirectUri was provided, the user is redirected there after a successful connection.

Bring Your Own OAuth App

Most teams can use PostPeer's managed OAuth apps and skip this part. Use Bring Your Own Keys when you need the connected account to authorize through your own platform app, brand, audit, or quota.

First, create the OAuth app in the platform's developer console. Set its callback URL to PostPeer's callback for that platform:

https://api.postpeer.dev/v1/connect/{platform}/callback

For Twitter, that would be:

https://api.postpeer.dev/v1/connect/twitter/callback

Then register the app credentials with PostPeer:

curl -X POST https://api.postpeer.dev/v1/apps/ \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "twitter",
    "name": "Acme Twitter OAuth App",
    "clientId": "YOUR_PLATFORM_CLIENT_ID",
    "clientSecret": "YOUR_PLATFORM_CLIENT_SECRET"
  }'

Save the returned app.id. Pass it as appId when you start the connect flow:

curl "https://api.postpeer.dev/v1/connect/twitter?appId=app_123&profileId=65ab123" \
  -H "x-access-key: YOUR_API_KEY"

PostPeer still handles the callback, token exchange, token storage, refresh, and posting. The difference is that the platform account is connected under your OAuth app instead of PostPeer's managed app.

Use the Apps API reference to list apps, rotate a stored client secret, or delete an app. You cannot change an app's platform or clientId after creation because existing refresh tokens are tied to that client ID. To switch to another OAuth app, create a new app and reconnect the account.

How It Works

1. Your app calls GET /v1/connect/{platform} to get an OAuth URL
2. Redirect the user to that URL (or open it in a new tab)
3. The user authorizes on the platform (Twitter, YouTube, etc.)
4. The platform redirects to PostPeer's callback
5. PostPeer exchanges the code for tokens and stores them encrypted
6. If redirectUri was set, the user is redirected back to your app

Bluesky: App Password Flow

Bluesky doesn't use OAuth redirects. The end user generates an App Password at https://bsky.app/settings/app-passwords and submits it once via a separate POST endpoint:

curl -X POST https://api.postpeer.dev/v1/connect/bluesky/auth \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "alice.bsky.social",
    "password":   "xxxx-xxxx-xxxx-xxxx"
  }'

identifier is the user's handle or DID; password must be an app password, not the account password. The response includes the integration object — use integration.id as accountId when posting. See the Bluesky platform docs for full details.

Status Codes