Skip to main content

Tiktok Integration

This document outlines the integration developed to support OAuth authentication with TikTok using login-kit and to perform automated daily reporting via the TikTok API on behalf of multiple TikTok accounts.

OAuth App Configuration​

The integration is based on an OAuth application configured in the TikTok Developer Portal. The developer account used for access is:

[email protected]

The application is currently operating in sandbox mode, which is sufficient for our needs. The sandbox environment supports a limited number of test users, and this constraint is acceptable for our usage.

We utilize the sandbox version of the app everywhere in production to avoid TikTok's review and approval process. The list of allowed users (whitelist) is configured at:

Sandbox Configuration

Only whitelisted users can authenticate; any login attempt from a non-whitelisted user will fail in any environment.

Redirect URL Restrictions​

Like all OAuth apps, TikTok enforces strict redirect URI validation. All redirect URLs must be:

  • HTTPS
  • Whitelisted in the app settings

Currently, the following redirect URIs are configured and allowed:

https://local.fabn.dev:8443/users/auth/tiktok/callback
https://reports.aleteia.org/users/auth/tiktok/callback

Note: Additional review environments or domains must be added to the application settings to prevent redirect_uri mismatch errors during the OAuth flow.

Token Lifecycle and Storage​

Once a user successfully authenticates via TikTok OAuth, the system stores both the access_token and refresh_token.

  • Access Tokens are used to perform TikTok API requests.
  • Refresh Tokens are used to renew access tokens when expired.
  • Token Expiration: While the access token expiry is handled automatically, the refresh token has a hidden one-year expiration, not explicitly returned by the API.

Important: Once a year, users must relink their TikTok accounts via the web UI to refresh the refresh_token.

This can be done by visiting:

info

Accounts Page

and selecting an individual account. The "Refresh credentials" button re-authorizes the app and stores a fresh token set. The panel shows a red banner once refresh_token_expires_at is in the past.

What happens when the authorization expires​

TikTok answers a refresh made with a dead token with invalid_grant. The integration treats that as terminal:

  • Tiktok::Service raises Tiktok::ReauthorizationRequired and writes refresh_token_expires_at back to the current time, so the admin panel stops presenting the connection as healthy.
  • Tiktok::UploadReportJob discards the job instead of retrying it: no retry can mint a new refresh token, and the retries only bury the one log line that says the account must be relinked. The discard logs the error (it reaches Datadog Error Tracking) and increments aleteia.tiktok.reauthorization_required.

The daily fan-out also publishes aleteia.tiktok.refresh_token_days_left per account and logs a warning once the authorization is within 30 days of expiring, which is the signal to relink before the reports stop. Each successful upload increments aleteia.tiktok.report_uploaded: its absence is what tells the monitors the integration is down, whatever the cause.

Daily Reporting Job​

For each connected TikTok account, the integration generates a daily CSV report containing the view statistics retrieved via the TikTok API.

  • The job handles token refresh as needed before making requests.
  • The resulting CSVs are uploaded to an S3 bucket using a naming convention aligned with the analytics team’s expectations.
  • These reports are then ingested into the big data system for further analysis.

Summary​

  • Uses login-kit for OAuth integration.
  • Works in sandbox mode to avoid full app review.
  • Access is limited to whitelisted users.
  • Redirect URLs must be HTTPS and explicitly allowed.
  • Refresh tokens expire silently after 1 year.
  • Daily report CSVs are stored in S3.
  • Accounts must be relinked yearly via the admin UI, warned by aleteia.tiktok.refresh_token_days_left 30 days ahead.

This setup ensures a secure, automated, and low-maintenance integration with TikTok suitable for reporting and analytics purposes.