Skip to main content

​
Overview

Connecting TikTok Ads lets the dashboard:
  • Create, update, pause, resume, and remove campaigns, ad groups, and ads.
  • Upload creative assets (image, video) into the connected advertiser.
  • Pull spend, impressions, clicks, conversions, and conversion value via the Reporting API.
  • Run native creative experiments via TikTok’s A/B test feature.
  • Receive realtime ad-disapproval and account-status events via webhooks.
The integration uses the Marketing API v1.3 with OAuth 2.0 authentication.

​
Prerequisites

Before connecting, make sure you have:
  1. A TikTok For Business account with at least one advertiser.
  2. Admin or operator role on the advertiser.
  3. (Optional) A TikTok Pixel or Events API source for conversion tracking.

​
OAuth scopes

The connection requests the standard advertiser-management scope set required to read account info, manage campaigns, and pull reports.

​
Connect

  1. Open the Paid UA → Integrations page in the dashboard.
  2. Click Connect on the TikTok Ads tile.
  3. Sign in with the TikTok For Business account.
  4. Approve the requested scopes.
  5. Pick the advertiser to use.

​
Token lifetime

TikTok access tokens expire 24 hours after issuance with no refresh extension. The background paid-ua-token-refresh cron rotates tokens 6 hours before expiry. If rotation fails, the integration is downgraded to read-only and a banner appears on the connections page until you reauthorize.

​
What lives on the platform vs the dashboard

Lives on TikTokLives on the dashboard
Campaign / ad-group / ad idsSpend caps + agent-control matrix
Creative libraryVendor-neutral creative briefs
Audience configurationsIdempotency keys + retry attempts
Reporting metricsDaily roll-ups in ua_daily_metrics

​
Webhooks

TikTok posts ad-status and account-status events to: 
POST /api/v1/integrations/webhooks/tiktok
Signature: HMAC-SHA256 over the raw body keyed by the platform-side TIKTOK_WEBHOOK_SIGNING_KEY_CURRENT secret. The TIKTOK_WEBHOOK_SIGNING_KEY_PREVIOUS secret is also accepted during a 7-day rotation window.

​
Disconnect

Disconnecting revokes the dashboard’s stored OAuth token and stops all background syncs. Campaigns created via the dashboard remain on the platform — disconnect does not pause or delete them.

​
Limits

  • Token lifetime: 24 hours; rotated 6 hours before expiry by cron.
  • Rate limits: per-advertiser token bucket; 429s back off via the platform-specific retry header.
  • Creative size: image up to 30 MB, video up to 500 MB; format-specific limits enforced server-side before upload.