Configuration

Plugin settings

At Settings → Plugins → Tokr, or in config/tokr.php:

<?php

return [
    'clientKey' => '$TIKTOK_CLIENT_KEY',
    'clientSecret' => '$TIKTOK_CLIENT_SECRET',
    'refreshInterval' => 3600,
    'refreshOnRequest' => true,
    'videosPerRefresh' => 40,
    'keepRemovedVideos' => false,
    'includeCss' => true,
    'scopes' => [
        'user.info.basic',
        'user.info.profile',
        'user.info.stats',
        'video.list',
    ],
];

Setting	Default	What it does
`clientKey`	—	TikTok app client key. Accepts an env var.
`clientSecret`	—	TikTok app client secret. Accepts an env var.
`redirectUri`	auto	Override the OAuth redirect URI. Only needed behind a proxy.
`scopes`	four	Scopes to request. Config file only — not editable in the CP.
`refreshInterval`	`3600`	Seconds before stored videos count as stale. Capped at 18000.
`refreshOnRequest`	`true`	Queue a refresh job when a stale feed is requested.
`videosPerRefresh`	`40`	How many recent videos to pull per account, per refresh.
`keepRemovedVideos`	`false`	Keep videos TikTok no longer returns.
`includeCss`	`true`	Register Tokr's stylesheet when rendering a feed.

refreshInterval is the one to get right

TikTok's cover_image_url values are signed and stop working roughly six hours after they are issued. That is TikTok's constraint, not Tokr's, and there is no way to extend it.

So the refresh interval is not really a cache-tuning knob — it is the thing keeping your thumbnails alive. Tokr caps it at 18000 seconds (five hours) to leave an hour of headroom. The default of one hour is a good place to stay unless you have a reason to move.

If thumbnails go blank a few hours after a deploy, this is why: the refresh stopped running, not the images breaking.

Feed options

Each feed is configured at Tokr → Feeds.

Option	What it does
Handle	What you pass to `craft.tokr.render()`
Account	Which connected account this feed pulls from
Layout	Grid, masonry, carousel or list
Number of videos	How many the feed shows, 1–200
Columns	Independent desktop / tablet / mobile counts, 1–12
Gap	Space between videos in pixels
Profile header	Avatar, name, bio and counts above the videos
Follow button	Links to the TikTok profile
Captions	Caption under each video, hashtags and mentions linked
Like and comment counts	Per video, and the profile counts in the header
Play icon	The overlay triangle
Click behaviour	Lightbox, open on TikTok, or nothing
Load more	Render everything, reveal in batches

Columns respond to the container, not the viewport

The breakpoints are CSS container queries against the feed's own width. A feed in a narrow sidebar gets its mobile column count on a desktop screen, which is almost always what you wanted.

Styling

Tokr ships one stylesheet, scoped under .tokr, driven by custom properties:

.tokr {
    --tokr-accent: #fe2c55;   /* follow button */
    --tokr-radius: 8px;       /* thumbnail corners */
    --tokr-gutter: 12px;      /* overridden per feed */
}

Set Include Tokr's CSS to off to drop it entirely and write your own.

Permissions

Two, both under Tokr in the user group settings:

Manage TikTok feeds
Connect and manage TikTok accounts

Give editors the first and not the second if you want them arranging feeds without being able to disconnect the account underneath.