White-Label Integration

Overview

The PostPulse white-label (Connect) integration lets you offer multi-platform social publishing to your users without building any of the OAuth, scheduling, or platform publishing infrastructure yourself. You authenticate as a partner using a single machine-to-machine credential, and you act on behalf of your end-users by passing a lightweight identity header on every request.

How It Works

Three actors are involved: your backend (holds the M2M credential), your end-user (clicks "Connect Instagram" inside your product), and PostPulse (handles the OAuth dance with the social platform and stores the tokens).

Prerequisites

Authentication (M2M)

All white-label endpoints accept a standard Auth0 client credentials bearer token. Issue one token, cache it until it expires, and reuse it across all of your users.

Request a token

POST https://auth.post-pulse.com/oauth/token
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "grant_type": "client_credentials",
  "audience": "https://api.post-pulse.com"
}

The response contains an access_token and expires_in (seconds). Cache the token until shortly before expiry, then refresh.

Provision a User

The first time one of your end-users does anything social-related, provision them. The call is idempotent on (apiClientId, externalUserId) — safe to call repeatedly.

Endpoint

POST https://api.post-pulse.com/v1/connect/users

POST /v1/connect/users
Authorization: Bearer <m2m_access_token>
Content-Type: application/json

{
  "externalUserId": "user_42",
  "name": "Jane Doe",
  "email": "[email protected]"
}

Response

{
  "uuid": "0fe1b3a2-8b40-4d4c-9bb9-2f0d9dca57ad",
  "name": "Jane Doe",
  "email": "[email protected]"
}

Persist the returned uuid alongside your own user record. From this point forward, send it on every API call as either:

• X-Connect-User-Id: <uuid> — using the PostPulse UUID, or
• X-Connect-External-User-Id: <externalUserId> — using your own ID directly.

Both headers are equivalent; pick whichever fits your data model.

Connect a Social Account

Connecting a social account is the only step that involves a user-visible browser redirect. PostPulse hosts a thin OAuth bridge at app.post-pulse.com/oauth/connectthat handles the platform-specific OAuth flow on your behalf.

Step 1: Generate the Connect URL

POST /v1/connect/authorize-url
Authorization: Bearer <m2m_access_token>
x-api-key: YOUR_CLIENT_ID
X-Connect-User-Id: <uuid_from_provision>
Content-Type: application/json

{
  "platform": "INSTAGRAM",
  "redirectUri": "https://yourapp.com/connected"
}

Supported platform values: INSTAGRAM, FACEBOOK, YOUTUBE, TIKTOK, X_TWITTER, LINKEDIN, THREADS.

The response body is a single string — a short-lived signed URL such as https://app.post-pulse.com/oauth/connect?whitelabel_state=eyJhbGc....

Step 2: Open the URL in a browser

Open the returned URL in the user's browser (web), an in-app browser, or a system browser tab (mobile). PostPulse will:

• Verify the signed state and PKCE parameters.
• Redirect the user to the social platform's authorization screen.
• Receive the platform callback and exchange it for tokens.
• Store the tokens against your end-user.
• Redirect the browser to the redirectUri you supplied.

When you receive the redirect at redirectUri, the connection is complete — no extra exchange is required from your side. Refresh your UI / call /accountsto reflect the new connection.

Publishing & Media

Once an account is connected, the rest of the PostPulse API is identical to the standard product — just keep sending the partner auth headers.

List a user's connected accounts

GET /v1/accounts
Authorization: Bearer <m2m_access_token>
x-api-key: YOUR_CLIENT_ID
X-Connect-User-Id: <uuid>

Asynchronous media import (recommended for large files)

For videos and large images, use the asynchronous import endpoint and poll until status: "READY":

POST /v1/media/upload/import
{
  "url": "https://cdn.example.com/big-video.mp4",
  "filenameHint": "promo.mp4"
}

GET /v1/media/upload/import/{id}    # poll: QUEUED -> DOWNLOADING -> READY

Schedule a post

POST /v1/posts
Authorization: Bearer <m2m_access_token>
x-api-key: YOUR_CLIENT_ID
X-Connect-User-Id: <uuid>
Content-Type: application/json

{
  "platform": "INSTAGRAM",
  "accountId": 12345,
  "content": "Hello from your app",
  "mediaPaths": ["<path_returned_by_import>"],
  "scheduledTime": "2026-05-10T15:00:00Z",
  "publicationType": "REEL"
}

For the full schema of /posts, including platform-specific fields, see the API Documentation. Behaviour is identical to the non-white-label flow.

Reference: Required Headers

Every white-label call takes the same three headers. Memorise these and you know the integration.

Calls to /connect/users only need Authorization — you don't have a user UUID yet at that point.

Demo App

We maintain an open-source Flutter demo — VibeStudio Mobile Demo — that shows the full end-to-end integration: M2M auth, user provisioning, connecting accounts via deep-link, async media import, and scheduling posts.

View Demo on GitHub →

What the demo covers:

• Client-credentials token caching with expiry tracking.
• Transparent getOrCreateUser using externalUserId.
• OAuth bridge launch with a custom URL scheme (vibestudio://callback).
• Asynchronous media import with progress polling (QUEUED → DOWNLOADING → READY).
• Platform-specific publish settings (Instagram Reels, TikTok privacy level, etc.).

Get Access

White-label access is provisioned per partner. Email [email protected] with:

• A short description of your product and how social publishing fits in.
• Estimated user volume and target launch date.
• The redirect URIs (web and / or mobile) you'll be using.

We'll issue your Auth0 client credentials and walk you through a sandbox integration.