Setting up your TikTok developer app

Montage Engine talks to TikTok through an app you register. Approval belongs to your registration, on your domain — that keeps your account and your data entirely under your control.

Why you need your own app

TikTok approvals attach to a specific developer app (a client_key plus its registered URLs), never to a piece of software. Since Montage Engine is self-hosted, every operator registers their own app and owns their own approval — the same model used by other self-hosted social tools. There is no shared key: your posts go through your credentials only.

1 — Create the app

Register at developers.tiktok.com and create an app.
Add the products Login Kit and Content Posting API.
Request the scopes Montage Engine uses: user.info.basic, user.info.profile, user.info.stats, video.list, video.upload. (If you trim any in the portal, mirror it in TIKTOK_SCOPES.)
Platform: Web.

2 — Start in the sandbox

Create a sandbox from your app page and add your own TikTok account as a target user. Sandboxes need no review: you can connect, bootstrap your posting history, and run the full metrics side immediately using the sandbox credentials in .env.

3 — Domains

Redirect URI: register https://app.yourdomain.com/api/tiktok/auth/callback and set TIKTOK_REDIRECT_URI to the same value. It must be public HTTPS — TikTok rejects localhost for web apps, sandbox included. A temporary cloudflared tunnel --url http://localhost:8080 URL works for a one-time connect while you set up a proper tunnel.
URL property: verify ownership of your app hostname in the portal (DNS TXT is the least fuss). Required before TikTok will pull draft images from TIKTOK_PUBLIC_BASE_URL.

4 — What works before any review

Capability	Unreviewed / sandbox
Connect account, bootstrap history, metrics + charts	Works (target users only)
Send drafts to a private account	Works
Send drafts to a public account	Blocked until your app passes review and the Content Posting audit

Other unaudited limits: at most 5 pending drafts per rolling 24 hours, and a cap on posting users per day. Montage Engine surfaces these as friendly errors.

5 — Review, then audit

Two separate gates lift the restrictions:

App review takes your app live. TikTok expects a real, functional product behind the submission: a developed website describing it (with visible Privacy Policy and Terms links), an accurate description, only the scopes you use, and a demo video recorded against your sandbox showing the end-to-end flow on a domain that matches your website URL.
Content Posting audit (submitted after you're live) lifts the private-account restriction so drafts can go to your public account.

Be accurate and specific in the submission — describe what your instance does, show the real UI in the video, and expect that a clarification round is normal. Review feedback appears under your app's History tab in the portal.

6 — Wire up your instance

# .env
TIKTOK_CLIENT_KEY=…            # sandbox creds while testing, production creds once live
TIKTOK_CLIENT_SECRET=…
TIKTOK_REDIRECT_URI=https://app.yourdomain.com/api/tiktok/auth/callback
TIKTOK_PUBLIC_BASE_URL=https://app.yourdomain.com

Then connect from the app's TikTok page — the first connect bootstraps your full posting history automatically.

Troubleshooting

Error	Meaning
`url_ownership_unverified`	The domain serving your images isn't verified as a URL property — verify it (DNS TXT) and check `TIKTOK_PUBLIC_BASE_URL`.
`unaudited_client_can_only_post_to_private_accounts`	Your app hasn't passed the Content Posting audit yet — send to a private account, or finish review + audit.
`spam_risk_too_many_pending_share`	5 drafts are already waiting in the TikTok inbox from the last 24h — post or discard some first.
Preflight "public image URL is not reachable"	Your tunnel is down or `TIKTOK_PUBLIC_BASE_URL` is wrong — the instance checks its own public URL before calling TikTok.
`scope_not_authorized`	The connected account didn't grant a scope the app needs — reconnect and approve everything requested.