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 "Regenerate Token" function allows users to re-authorize the app and obtain a fresh token set.

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.

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