---
description: "White-label guide: embed Upload-Post in your SaaS. Create a profile per user, generate a JWT connect URL, and post on their behalf via the API."
sidebar_position: 4 # Adjust position as needed within the Guides category
title: White-label Integration
---

# White-label Integration Guide

![Profiles diagram](/img/profiles-diagram.png)

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](../api/connect-api.md)): 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](../api/user-profiles.md#create-user-profile)

### 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](../api/user-profiles.md#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](../api/user-profiles.md#endpoint-generate-jwt-url)

**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](../api/connect-api.md). 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](../api/upload-photo.md) or [Upload Video](../api/upload-video.md), 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](../api/user-profiles.md#get-user-profiles)

## 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](./connecting-accounts.md)**

## 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:

```bash
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](../api/upload-photo.md)
*   [Upload Video API Reference](../api/upload-video.md)