Skip to content

Get TikTok posting credentials

Set up a TikTok for Developers app so keryx auth tiktok can capture a refresh token and keryx post tiktok can publish a reel via the Content Posting API (Direct Post). This mirrors the YouTube credentials guide; the differences are TikTok's non-standard OAuth (client_key, hex PKCE, a rotating refresh token) and a mandatory audit before you can post anything but SELF_ONLY.

Status: app-registration steps (§1–§5) are ready to follow now — the audit is the long-lead item, so start it early. Posting is SELF_ONLY until it passes (spec 0008-tiktok.md).

What you need

  • A TikTok account to post to (added as a sandbox target user during development).
  • ~20 minutes for the app setup; the content-posting audit is separate and takes weeks — posts stay SELF_ONLY (private to the creator) until it's done, which is fine for building and testing.

1. Create the app (and a sandbox)

  1. Go to TikTok for Developers → https://developers.tiktok.com/ → Manage apps → create an app.
  2. Add a Sandbox to test without submitting for review. Note its client key and client secret:
  3. platforms.tiktok.client_key (non-secret) — goes in keryx config.
  4. TIKTOK_CLIENT_SECRET (secret) — env var / keychain, never committed.

2. Add the products & scopes

  1. Add Login Kit and the Content Posting API to the app.
  2. Enable Direct Post for the Content Posting API (so keryx publishes straight to the profile, not just to drafts).
  3. Request scopes user.info.basic and video.publish.

3. Register the redirect URI (Desktop loopback)

keryx is a Desktop app, so register a loopback redirect — under Login Kit → Redirect URI, on the Desktop tab (tick the Desktop platform):

http://127.0.0.1:*/callback/

The wildcard * port lets keryx pick any free port at runtime; plain http on 127.0.0.1/localhost is allowed for Desktop apps. keryx auth tiktok then runs a local callback server and captures the code automatically (same as YouTube) — no hosted page, no copy-paste. (Only TikTok Web apps are barred from loopback; Desktop apps require it.) If the console rejects the /callback/ path, use http://127.0.0.1:*/.

No domain verification needed. That step is only for pull_by_url media transfer; keryx uploads the file directly (FILE_UPLOAD).

4. Sandbox limits & the audit (the long pole)

While unaudited / in sandbox:

  • All posts are forced SELF_ONLY (visible only to the creator).
  • Only 5 user authorizations per 24 hours, and only your target test users can authorize.
  • Public posting requires passing TikTok's Content Posting audit (weeks; you must demonstrate a compliant UX). Until then keryx keeps platforms.tiktok.privacy: SELF_ONLY.

For now: create the app + sandbox (§1), add the products/scopes and enable Direct Post (§2), register the redirect (§3), add your TikTok account as a target user, and authorize. Defer the audit until posting is confirmed on SELF_ONLY.

Official references

  • TikTok for Developers — Content Posting API (Direct Post) and Get Started.
  • TikTok for Developers — Login Kit / Manage User Access Tokens (OAuth v2) and Login Kit for Desktop (PKCE: hex-encoded SHA256 challenge).
  • TikTok for Developers — Sandbox mode.

5. Authorise keryx

With the client key in config (platforms.tiktok.client_key) and the secret in the environment (TIKTOK_CLIENT_SECRET):

keryx auth tiktok

It runs a local http://127.0.0.1:<port>/callback/ server and prints/opens the TikTok authorize URL. Approve the permissions; TikTok redirects back to the loopback and keryx captures the code automatically, exchanges it for a refresh token, and stores it (keychain on a desktop, else the config file). platforms.tiktok.enabled flips true.

  • Remote/headless box: the redirect targets 127.0.0.1:<port> on your machine. Reach it via an SSH port-forward, or — since the browser lands on a dead 127.0.0.1 page showing the code in the address bar — copy that URL and paste it at the prompt (the automatic fallback). Pin a port with --redirect http://127.0.0.1:<port>/callback/ if you need to forward it.

  • Non-interactive: pass the code directly with keryx auth tiktok --code <code>.

  • The rotating refresh token: TikTok access tokens last ~24h, so every keryx post tiktok mints a fresh one from the refresh token — and TikTok may hand back a new refresh token on that call, which keryx persists immediately. Don't copy the stored refresh token between machines; whichever posts last holds the only valid one.

Once authorised, keryx post tiktok publishes a rendered reel as a SELF_ONLY post (until the audit lifts the cap). The capture flow reuses keryx auth.