Installation

Requirements

• Craft CMS 5.3 or later
• PHP 8.2 or later
• A TikTok for Developers app with Login Kit and Display API added
• HTTPS on the domain you connect from — TikTok will not redirect back to plain HTTP

Install

composer require justinholtweb/craft-tokr
php craft plugin/install tokr

Or find Tokr in the Craft Plugin Store and install it from there.

Tokr is a single paid edition, $99 one-off. There is no free tier and nothing is gated — the plugin you install is the whole plugin.

Nothing happens until you connect

Installing Tokr creates its three tables and adds a Tokr item to the control panel nav. It does not contact TikTok, and it has nothing to render, until you have connected an account.

Create the TikTok app

TikTok's developer portal is the slow part of this. Do it first.

1. Create an app at developers.tiktok.com.
2. Add the Login Kit and Display API products to it.

3. Under Login Kit, add a redirect URI. Tokr shows the exact value it expects at Settings → Plugins → Tokr — it looks like:

   https://example.com/tokr/oauth/callback
   

   TikTok matches this string character for character. A trailing slash, www. where you have no www., or http:// instead of https:// all fail with a redirect-uri error.

4. Request the scopes you need:

   Scope	Required	Gets you
   user.info.basic	Yes	Display name, avatar, open ID
   video.list	Yes	The videos themselves
   user.info.profile	No	Username, bio, profile link, verified badge
   user.info.stats	No	Follower, following, like and video counts

   Only request what your app has been approved for. Tokr drops fields belonging to a scope you were not granted rather than failing the whole request, but asking for an unapproved scope fails authorization outright.

Add the credentials

Copy the client key and secret from the TikTok app into Settings → Plugins → Tokr.

Both fields take environment variables, which is the right way to handle the secret:

# .env
TIKTOK_CLIENT_KEY="awxxxxxxxxxxxxxxxx"
TIKTOK_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

// config/tokr.php
return [
    'clientKey' => '$TIKTOK_CLIENT_KEY',
    'clientSecret' => '$TIKTOK_CLIENT_SECRET',
];

Connect an account

Tokr → Accounts → Connect an account sends you to TikTok's authorization screen and back. On return, Tokr stores the tokens encrypted with your securityKey and immediately pulls the profile and the first batch of videos.

While your TikTok app is still in sandbox, only accounts you have added as target users in the developer portal can complete this. Everyone else gets an error from TikTok before they ever reach your site.

Then make a feed

A feed is a saved set of display options with a handle. Create one under Tokr → Feeds, then:

{{ craft.tokr.render('homepage') }}

See Usage for what else you can do with it.