PostZen
Connect

Complete an OAuth connection

POST
/v1/connect/{platform}

Exchanges an OAuth authorization code for tokens and connects the account to the specified profile. This endpoint requires a read-write API key.

Authorization

bearerAuth
AuthorizationBearer <token>

PostZen API key.

In: header

Path Parameters

platform*string

Social platform to connect. twitter is accepted as an alias for x.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/connect/twitter" \  -H "Content-Type: application/json" \  -d '{    "code": "AQTF0v6PZnq1yTkGxg3M4S8d",    "state": "3q2Xv8Zk1mR5tY7wA9bC4dE6",    "profileId": "jh72r5nqk9wx3v8m1t4cz6bs0fy5dg3e"  }'
{  "message": "Account connected successfully",  "platform": "twitter",  "profileId": "jh72r5nqk9wx3v8m1t4cz6bs0fy5dg3e",  "status": "connected",  "accounts": [    {      "_id": "j97kp4mw2xnv6r1t8c3zq5bs9fh0yg4d",      "platform": "twitter",      "providerAccountId": "1934567890123456789",      "profileId": {        "_id": "jh72r5nqk9wx3v8m1t4cz6bs0fy5dg3e",        "name": "Marketing Team",        "slug": "marketing-team",        "color": "#4caf50"      },      "username": "acme",      "displayName": "Acme",      "status": "connected",      "isActive": true,      "connectedAt": "2026-06-19T16:00:00.000Z"    }  ]}
{  "error": "oauthCallbackFailed",  "errorDescription": "OAuth callback did not complete a matching platform connection"}
{  "error": "Unauthorized"}
{  "error": "Add a payment method before connecting more than 2 social accounts.",  "code": "paymentRequired",  "reason": "freeTierExceeded",  "documentationUrl": "https://docs.postzen.dev/api-reference/connect/create-connect-url",  "dashboardUrl": "https://app.postzen.dev/settings?tab=billing",  "details": {    "freeTierAccountLimit": 2,    "currentAccountCount": 2,    "hasPaymentMethod": false  }}
{  "error": "oauthStateUserMismatch"}
{  "error": "Not found"}
{  "error": "linkedinOauthFailed"}

Create an OAuth connect URL GET

Initiates an OAuth connection flow and returns an authorization URL to redirect the user to. The OAuth state expires after 10 minutes. This endpoint requires a read-write API key. For `bluesky`, the returned `authUrl` is a PostZen-hosted page where the user enters their Bluesky handle and app password (no developer app or OAuth redirect is required); the connection completes when they submit that form. For `telegram`, the returned `authUrl` is a PostZen-hosted page that issues a short-lived access code (there is no OAuth grant and no Telegram authorization screen); the connection completes when the user adds @PostZenScheduleBot as an administrator of a channel or group and sends that code to the bot.

Create a presigned media upload URL POST

Creates a presigned URL for uploading an image, video, GIF, or PDF to PostZen-hosted storage. Upload the file with an HTTP `PUT` to `uploadUrl`, then reference `publicUrl` in post `mediaItems`. This endpoint requires a read-write API key.