White-label Integration Guide

This guide explains how to integrate Upload-Post directly into your own platform. This allows your users to connect their social media accounts securely through Upload-Post, enabling your platform to manage their profiles and posts via the API on their behalf.

Integration Flow Overview

The core idea is to create a unique profile within Upload-Post for each user on your platform who wants to connect their social accounts. You then let the user link their accounts in one of two ways:

• Hosted connect page (fastest): generate a secure access_url and send the user there. You can brand it with your logo, title, texts and language — no frontend work needed. This is the flow described step by step below.
• Your own connect page (Connect API): build the connection UI inside your product, on your own domain, with your own design. Your page requests each platform's authorize URL from the API and Upload-Post handles the OAuth exchange behind the scenes.

Once linked (either way), your platform interacts with the Upload-Post API using the user's unique identifier.

Step-by-Step Integration

Step 1: Create a User Profile

For each user on your platform, you need to create a corresponding profile in Upload-Post. This is done by making a POST request to the /api/uploadposts/users endpoint.

• Requirement: You must provide a unique username in the request body. This username should be a stable identifier that links the Upload-Post profile back to the user on your platform (e.g., your internal user ID).
• Authentication: Remember to include your Authorization: Apikey YOUR_API_KEY header.
• Result: The API will respond with details of the created profile, confirming the username.

➡️ See details: Create User Profile API Reference

Step 2: Generate the Secure JWT URL

Once the profile exists, you need to generate a secure URL that your user will use to connect their social media accounts. Make a POST request to the /api/uploadposts/users/generate-jwt endpoint.

• Requirement: In the request body, provide the same unique username (from Step 1). You can also include the following optional fields:
  • redirect_url: A URL to which the user will be redirected after linking their account.
  • logo_image: A URL to a logo image for branding on the linking page.
  • redirect_button_text: (Optional) The text to display on the redirect button after linking. Defaults to "Logout connection".
  • connect_title: (Optional) Custom title text for the connection page.
  • connect_description: (Optional) Custom description text for the connection page.
  • platforms: (Optional) List of platforms to show for connection. Defaults to all supported platforms.
  • show_calendar: (Optional) Whether to show the calendar view on the connection page. Defaults to true.
  • readonly_calendar: (Optional) When true, shows only a read-only calendar view. Users cannot edit, delete, or create posts, and cannot connect or disconnect social accounts. Ideal for sharing a content calendar with end clients. Defaults to false.
  • language: (Optional) Forces the connection page language for this profile. Supported values: en, es, de, fr, pt, pl, tr. When omitted, the page auto-detects the visitor's browser language and falls back to English.
  • ui_labels: (Optional) A flat object of connect-page i18n keys → replacement strings, for white-label integrations that need to override UI text beyond connect_title/connect_description/redirect_button_text. Max 100 entries, values max 300 chars. See Custom UI Labels.
• Authentication: Include your Authorization: Apikey YOUR_API_KEY header.
• Result: The API will return a JSON object containing an access_url. This URL contains a secure token (JWT) valid for 48 hours.

➡️ See details: Generate JWT URL API Reference

Quick troubleshooting (common integration mistakes):

• If generate-jwt returns 404, call GET /api/uploadposts/users and verify the profile username exists.
• If profile creation returns 403, you hit your plan profile limit. Resolve limits before retrying JWT generation.
• Always treat profile creation and JWT generation as two explicit checked steps (do not ignore non-2xx responses).

Step 3: User Connects Accounts

Redirect your user to the access_url obtained in Step 2. This URL will open the Upload-Post connection interface, guiding the user through the process of securely connecting their desired social media accounts (like Instagram, TikTok, Facebook, etc.) to their profile.

Enhanced Connect Experience:

• Professional Navigation: Tab-based interface for easy switching between account connection and calendar view
• Calendar View (if enabled): Users can view their scheduled posts and upload history directly from the connect page
• Customizable Interface: You can control the branding, title, and available features through the JWT parameters
• Secure OAuth Flows: Upload-Post handles all authentication and token storage securely

The connection URL is valid for 48 hours, giving users ample time to complete the linking process.

Alternative — build your own connect page: if you want full control over the connection experience (your domain, your design, your copy), skip the hosted page entirely and use the Connect API. Your page calls POST /api/uploadposts/oauth/{platform}/start with the profile JWT from Step 2, redirects the user to the returned authorize_url, and Upload-Post sends them back to your redirect_url when the account is connected. The hosted page and the Connect API can be mixed freely — both link accounts to the same profile.

Step 4: Manage User Content via API

After the user successfully connects their accounts in Step 3, your platform can now use other Upload-Post API endpoints to manage content on their behalf.

• When making calls to endpoints like Upload Photo or Upload Video, you will typically include the user's unique username (the one you used in Step 1 and 2) in the request parameters to specify which profile's connected accounts should be used.
• You can also retrieve the list of profiles and their connected accounts using the GET /api/uploadposts/users endpoint.

➡️ See details: Get User Profiles API Reference

Connecting Accounts (manual credentials)

Some platforms (Discord, Telegram, Slack, Mastodon, Nostr, Lemmy, Dev.to, Hashnode, WordPress, Whop, Listmonk) connect with a manual credential — an incoming webhook, API token, or key — instead of OAuth, with no browser redirect. The full step-by-step for each lives in its own guide:

➡️ Connecting Social Accounts

Read-Only Calendar for Clients

If you're an agency managing content for clients, you can generate a read-only calendar link that lets your clients view their scheduled posts without being able to edit anything.

Use the readonly_calendar parameter when generating the JWT:

curl -X POST https://api.upload-post.com/api/uploadposts/users/generate-jwt \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "client_profile_123",
    "readonly_calendar": true,
    "logo_image": "https://youragency.com/logo.png",
    "connect_title": "Your Content Calendar"
  }'

The returned access_url will show:

• Social media channel for each post
• Scheduled date and time
• Visual (photo/video preview)
• Post text/caption

The client cannot:

• Edit, delete, or reschedule posts
• Connect or disconnect social accounts
• Access any other section of Upload-Post

This is ideal for agencies that need to share content calendars with end clients for approval or visibility.

Authentication

All API requests related to user profile management (/api/uploadposts/users and /api/uploadposts/users/generate-jwt) require authentication using your API Key. Include it in the Authorization header for every request:

Authorization: Apikey YOUR_API_KEY

Replace YOUR_API_KEY with the actual API key provided to you.

(Note: The /api/uploadposts/users/validate-jwt endpoint uses Bearer token authentication, as detailed in its specific documentation).

Next Steps

With the user profiles created and accounts linked, explore the other API references to start managing content:

• Upload Photo API Reference
• Upload Video API Reference