Skip to content
SocialRelay

TikTok setup

Registering a TikTok developer app for photo publishing, and what its audit gates.

TikTok publishing uses the Content Posting API. SocialRelay supports photo posts — one to ten images with a caption. Video publishing is not implemented.

TikTok gates public posts behind an audit

Until your app passes TikTok’s content-posting audit, everything it publishes is forced to private or self-only visibility. The API call succeeds and SocialRelay records it as published — but nobody else can see the post. This is TikTok’s restriction, not a bug in the application.

Prerequisites

  • A developer account at developers.tiktok.com
  • A TikTok account to publish from
  • A verified domain — TikTok requires you to prove you own the redirect host

1. Create the app

  1. In the TikTok developer portal, create an app.
  2. Add the Login Kit product, which provides OAuth.
  3. Add the Content Posting API product.
  4. Under Content Posting API, enable Direct Post. Without it the API can only create drafts, and SocialRelay publishes directly.

2. Verify the domain

TikTok will not accept a redirect URI on a host you have not verified. In the portal, add social.aitoolbucket.com as a verified property and complete the check it offers — usually a DNS TXT record or a file served from the domain root.

3. Redirect URI

text
https://social.aitoolbucket.com/api/oauth/tiktok/callback

TikTok requires HTTPS and does not accept localhost. For local development, tunnel your dev server and verify that hostname instead.

4. Scopes

SocialRelay requests exactly these:

text
user.info.basic   read the connected account's open id and username
video.publish     publish content directly
video.upload      upload the media for a post

The video.* naming is TikTok’s own and covers photo posts too — there is no separate photo scope.

5. Copy the credentials

TikTok calls these a Client Key and Client Secret, not a client ID — the environment variable names follow TikTok’s terminology.

bash
cd /var/www/creator

read -rsp "TIKTOK_CLIENT_KEY: " V && printf '\nTIKTOK_CLIENT_KEY="%s"\n' "$V" >> .env
read -rsp "TIKTOK_CLIENT_SECRET: " V && printf '\nTIKTOK_CLIENT_SECRET="%s"\n' "$V" >> .env

sudo systemctl restart creator-app creator-worker

What TikTok will accept

  • 1 to 10 images per photo post
  • Caption and hashtags, with the first 90 characters used as the post title
  • Images are pulled by TikTok from the URLs you supply, so those URLs must be publicly reachable over HTTPS

When a content package arrives with more than ten images, the review screen refuses to publish and asks you to remove the extras rather than silently truncating.

Publishing is asynchronous

TikTok’s API returns a publish_id immediately and processes the post afterwards, so a successful call does not yet mean a live post. SocialRelay records the publish id and can poll for the final state. If TikTok rejects the content during processing, the status comes back as failed even though the original request succeeded.

Troubleshooting

scope_not_authorized

The app does not have the requested scope approved, or Direct Post was never enabled. Re-check the Content Posting API configuration, then reconnect the account.

TIKTOK_TOKEN_EXPIRED

TikTok access tokens are short-lived. SocialRelay refreshes automatically when a token is within five minutes of expiring, but only if a refresh token was stored — which requires the original connection to have completed cleanly. Reconnect the account.

Unaudited client cannot post publicly

Expected before the audit. Posts land as private on the account. Submit the app for TikTok’s content-posting review to lift it.

TIKTOK_MEDIA_TOO_LARGE or a format error

TikTok could not fetch or decode an image. Confirm the URL is publicly reachable, served over HTTPS, and is a JPEG, PNG, or WebP.

See also the TikTok connection guide for the end-user flow.