TikTok Login Kit: OAuth flow and token lifecycle

How does TikTok OAuth work?

Key terms: client key, client secret, open_id and tokens

client_key

The app's public identifier. Sent in the authorization URL and in token requests.

client_secret

The app's confidential credential. Used only in server-side requests to /v2/oauth/token/ and /v2/oauth/revoke/; never shipped in a browser or mobile binary.

code

The authorization code returned to your redirect URI after the user consents. Exchange it for tokens right away.

access_token

Bearer token for API calls, valid for 24 hours after issuance.

refresh_token

Used to obtain a new access token; valid for 365 days after initial issuance. A refresh response may contain a different refresh token.

open_id

The TikTok user's unique identifier, returned with the token. Use it as the key of the connected account.

state

A random value you create before the redirect and compare on callback to block CSRF.

How to set up TikTok OAuth for a web app

1. 1

   Register redirect URIs

   Add up to 10 redirect URIs in the Login Kit settings. Each must be absolute, start with https, be under 512 characters, be static (no query parameters) and contain no # fragment.

2. 2

   Create and store a state value

   Generate a random string for every login attempt and keep it in the user's session or a short-lived cookie. TikTok's own web sample uses a short-lived cookie too.

3. 3

   Redirect to the authorization page

   Open https://www.tiktok.com/v2/auth/authorize/ with client_key, response_type=code, a comma-separated scope, redirect_uri and state. Add disable_auto_auth=1 to always show the consent page.

4. 4

   Validate the callback

   TikTok returns code, scopes and state, or error and error_description. Reject the request if state does not match, and compare the granted scopes with what you asked for.

5. 5

   Exchange the code on the server

   POST to https://open.tiktokapis.com/v2/oauth/token/ as application/x-www-form-urlencoded with client_key, client_secret, code, grant_type=authorization_code and the same redirect_uri. Desktop and mobile apps also send code_verifier.

6. 6

   Store tokens securely

   Save access_token, refresh_token, both expiry times and open_id, encrypted at rest. TikTok's web guide makes the server explicitly responsible for keeping the client secret and refresh token secure.

Login Kit in Python

Framework-agnostic handlers: session is whatever session storage your web framework provides.

import secrets
from socialift import TikTok

REDIRECT_URI = "https://app.example.com/oauth/tiktok/callback"
SCOPES = ["user.info.basic", "video.list", "video.publish"]

async def begin_login(session: dict) -> str:
    session["tiktok_state"] = secrets.token_urlsafe(32)
    async with TikTok.from_env() as tt:
        return tt.login_url(
            redirect_uri=REDIRECT_URI,
            state=session["tiktok_state"],
            scopes=SCOPES,
        )

async def finish_login(session: dict, code: str, state: str) -> dict:
    expected = session.pop("tiktok_state", "")
    if not expected or not secrets.compare_digest(state, expected):
        raise ValueError("OAuth state mismatch")
    async with TikTok.from_env() as tt:
        bundle = await tt.exchange_code(code, redirect_uri=REDIRECT_URI)
    return {
        "open_id": bundle.raw.get("open_id"),
        "access_token": bundle.access_token,
        "refresh_token": bundle.refresh_token,
        "expires_at": bundle.expires_at,
        "scopes": bundle.scopes,
    }

PKCE: web vs desktop vs mobile

TikTok's desktop guide computes code_challenge as the hex-encoded SHA-256 of the verifier — not the base64url encoding used in RFC 7636.

PKCE for desktop apps

The verifier must be 43–128 characters long and use only A–Z, a–z, 0–9 and -, ., _, ~.

import hashlib
import secrets
from socialift import TikTok

REDIRECT_URI = "http://127.0.0.1:3455/callback/"

def make_pkce() -> tuple[str, str]:
    verifier = secrets.token_urlsafe(48)                       # 64 characters
    challenge = hashlib.sha256(verifier.encode()).hexdigest()  # hex, as TikTok documents
    return verifier, challenge

async def desktop_login(state: str) -> tuple[str, str]:
    verifier, challenge = make_pkce()
    async with TikTok.from_env() as tt:
        url = tt.login_url(
            redirect_uri=REDIRECT_URI,
            state=state,
            code_challenge=challenge,
            code_challenge_method="S256",
        )
    return url, verifier

async def desktop_callback(code: str, verifier: str):
    async with TikTok.from_env() as tt:
        return await tt.exchange_code(code, redirect_uri=REDIRECT_URI, code_verifier=verifier)

Token lifetimes and what to do about them

yesno

Refresh daily, revoke on disconnect

from datetime import datetime, timedelta, timezone
from socialift import ApiError, TikTok

async def ensure_fresh(account: dict) -> dict:
    left = account["expires_at"] - datetime.now(timezone.utc)
    if left > timedelta(hours=2):
        return account
    async with TikTok.from_env() as tt:
        try:
            bundle = await tt.refresh_token(account["refresh_token"])
        except ApiError:
            account["status"] = "reconnect_required"
            return account
    account.update(
        access_token=bundle.access_token,
        refresh_token=bundle.refresh_token or account["refresh_token"],
        expires_at=bundle.expires_at,
    )
    return account

async def disconnect(account: dict) -> None:
    async with TikTok.from_env() as tt:
        await tt.revoke(account["access_token"])

Scopes and consent in practice

TikTok OAuth security checklist

• ▸Keep the client secret and refresh tokens on the server only, encrypted at rest.
• ▸Generate a fresh state for every login and reject callbacks where it does not match.
• ▸Register exact, static HTTPS redirect URIs; carry context in the state or session, not in query parameters.
• ▸Use PKCE with S256 in desktop apps and send code_verifier at exchange.
• ▸Refresh access tokens on a schedule shorter than 24 hours and persist rotated refresh tokens.
• ▸Revoke tokens with /v2/oauth/revoke/ when a user disconnects inside your product.
• ▸Log the log_id of failed API calls for TikTok support.