TikTok API Setup

Admin walkthrough for the TikTok integration. End-user flow: Connections → TikTok.

Overview

Form field	Options key
Client Key	tiktok_client-key
Client Secret	tiktok_client-secret
Status	tiktok_integration_status

ENV fallback: TIKTOK_CLIENT_KEY + TIKTOK_CLIENT_SECRET.

Field name is "Client Key", not "Client ID"

TikTok uses Client Key for what other portals call Client ID. Sosyabot's form labels match TikTok's naming.

Step-by-step on developers.tiktok.com

1. Sign in and register as a developer

https://developers.tiktok.com → sign in with the TikTok account that should own the app. Accept the developer terms.

2. Create a new app

Manage apps → Connect an app. Fill in:

• App name, icon, description.
• App category (e.g. Productivity, Social).
• Platform: Web.
• App's website URL: https://sosyabot.com.

3. Add the right products

Inside the app:

• Login Kit — required for OAuth.
• Content Posting API — required to publish videos.

4. Configure URL settings

In Login Kit settings:

• Redirect URIs: do not hardcode a domain. Copy the exact Callback URL shown on the admin page /admin/api-integration/tiktok (rendered live for this deployment). The pattern is:

  <BASE_URL>/api/v1/auth/tiktok/callback

  <BASE_URL> is your backend URL; /api/v1 is the configured API_PREFIX. See OAuth Callback URLs.
• Sosyabot uses the Direct Post flow (not Inbox), which has no extra redirect.

5. Request scopes

The required OAuth scopes are user.info.basic, video.publish, video.upload. Sandbox apps grant these immediately to invited testers; production apps require App Review (TikTok asks for a screencast and a privacy/data-handling document).

6. Submit for review (production only)

Once Sandbox testing is green, submit the app for review. Allow several weeks. Until approved, only invited tester accounts can connect.

7. Grab Client Key + Client Secret

App dashboard → App credentials. Copy Client Key and Client Secret.

Pasting into Sosyabot admin panel

/admin/api-integration/tiktok. Paste, Enable, Save, Test credentials.

Failure: TikTok integration disabled: client key/secret not configured.

Verification

/app/channels → Connect → TikTok → OAuth → approve. Try a 5–10 second mp4 from /app/publishing.

Troubleshooting

Symptom	Cause	Fix
TikTok integration disabled: client key/secret not configured	Admin + ENV empty	Steps 1–7.
Connect succeeds but publish fails with permission_error	App in Sandbox tier	Either invite the test account as a Sandbox tester, or submit for Production review.
redirect_uri_mismatch on consent screen	Redirect URI mismatch	Add the exact …/api/v1/auth/tiktok/callback.
Video upload returns video_size_too_large	Asset exceeds TikTok limits	TikTok caps at ~287 MB / 60 s for unverified accounts; check current limits in TikTok docs.

ENV fallback

TIKTOK_CLIENT_KEY=<your client key>
TIKTOK_CLIENT_SECRET=<your client secret>

After editing .env run ./service.sh restart.

Related

OAuth Credentials overview

TikTok user-side connect

OAuth Callback URLs