Skip to main content

Cookie Management

Why Cookies?​

Douyin and TikTok authenticate web API requests using browser session cookies — not API keys. The scraper impersonates a logged-in browser session using cookies you provide. Without valid cookies, platform-specific endpoints return authentication errors.

PlatformTypical Session Lifetime
Douyin7–30 days
TikTok7–30 days
TikTok (app)Similar

Cookies expire. When they do, affected endpoints will return errors. The /api/hybrid/video_data endpoint for TikTok URLs continues to work without cookies.

Which Service Name to Use​

When calling POST /api/hybrid/update_cookie, the service param must be one of:

Service NameAffects
douyinAll Douyin web endpoints
tiktok_webTikTok web API endpoints
tiktok_appTikTok app API endpoints (optional)

No container restart required. The API reads cookies at call time.

curl -X POST http://video-scraper-api:80/api/hybrid/update_cookie \
  -H "Content-Type: application/json" \
  -d '{
    "service": "douyin",
    "cookie": "YOUR_FULL_COOKIE_STRING_HERE"
  }'

Repeat for tiktok_web and tiktok_app as needed.

  1. Open Chrome or Firefox
  2. Log into douyin.com or tiktok.com
  3. Open DevTools → Network tab
  4. Reload the page
  5. Click any request to douyin.com or tiktok.com
  6. In the Request Headers, find the Cookie header
  7. Copy the entire value — it's a long semicolon-separated string

Alternatively, use a browser extension like Cookie-Editor (FOSS, available for Chrome/Firefox):

  • Install the extension
  • Navigate to the site
  • Click the extension → Export → Export as Header String

Manual cookie rotation doesn't scale. The recommended automated approach uses Playwright with a persistent browser context:

How it works:

  1. You log in once interactively using cookie-login-setup.py — this saves an authenticated browser profile to disk
  2. A daily cron job (cookie-refresh.py) opens a headless browser using the saved profile, extracts fresh cookies, and pushes them to the API
  3. No repeated logins — the saved profile maintains the session

Why this is low-risk: The script doesn't automate the login — it reads from an already-authenticated persistent session. ByteDance's bot detection is focused on login behavior, not cookie extraction from existing sessions.

Files (managed by DevOps Dan):

/opt/nops-labs/Video-Scraper-API/
├── cookie-login-setup.py    ← Run once interactively
├── cookie-refresh.py        ← Runs daily via cron
└── browser-profile/         ← Saved Playwright browser state
    └── douyin/
    └── tiktok/

Cron log:

/opt/nops-labs/Video-Scraper-API/logs/cookie-refresh.log

Check this log if a cookie-dependent endpoint starts returning errors.

If a Douyin or TikTok endpoint returns errors:

  1. Check the log: tail -50 /opt/nops-labs/Video-Scraper-API/logs/cookie-refresh.log
  2. Run the refresh manually: python3 /opt/nops-labs/Video-Scraper-API/cookie-refresh.py
  3. If the session itself expired (login required): re-run cookie-login-setup.py to re-authenticate

The hybrid endpoint for TikTok will continue working even when TikTok cookies are stale.