Trakt Token Relay

Automated Trakt token refresh and distribution of a fake config for media players. Designed for use with the Elementum add-on in Kodi via the Elementum Trakt Updater add-on to share tokens from a single account across multiple devices. May also be useful for other projects.

Alternative

Using different Client ID and Client Secret, or moving them to settings and recompiling Elementum. If you have many devices, this may look suspicious to Trakt's anti‑fraud system.

Quick Start

1. Preparation

• Click Use this template and create a Private repository or create a new one and copy all the files.
• Make sure the repository is PRIVATE!
• Make sure the repository contains the following files:
  • .github/workflows/init.yml
  • .github/workflows/keep-alive.yml
  • .github/workflows/trakt_token_relay.yml
  • trakt_token_relay.py
  • scripts/init.py

2. Get a Personal Access Token (PAT) on GitHub

1. Go to Settings → Developer settings → Personal access tokens → Tokens (classic).
2. Click Generate new token (classic).
3. Enter a name (e.g., trakt-token-relay).
4. Select scopes: repo and gist.
5. Generate the token and copy it.

3. Deployment. Run the Initialization

1. In your repository, go to the Actions tab.
2. Select the Initialize Trakt Token Relay workflow.
3. Click Run workflow.
4. Fill in the fields:
   • TRAKT_USERNAME – your Trakt username (as shown in your profile or from Elementum settings.xml>trakt_username).
   • TRAKT_REFRESH_TOKEN – the initial refresh_token (can be copied from Elementum settings.xml>trakt_refresh_token after Elementum is authorised).
   • GIST_TOKEN – the Personal Access Token (PAT) you copied earlier.
5. Click Run workflow.

After successful execution, you will see a link to the client config on Gist at the bottom of the page. Save it – you will need it for configuring your media player. It is recommended to delete the logs of Init Trakt Token Relay to hide the Client config URL in the init summary in case the repository is no longer private.

4. Run the Main Workflow

You can now run the main Trakt Token Relay workflow (manually or wait for the scheduled run). It will run every 12 hours. Planned improvements include triggering the refresh 1–2 hours prior to the expires_in threshold, or setting a fixed interval of 23 hours (594,000 seconds).

5. Use the Link in Your Media Player

In your media player’s Trakt settings (e.g., service.elementum.trakt.updater), provide the obtained link as the JSON URL. Elementum Trakt Updater will automatically fetch the current access_token according to its settings.

How It Works

• The actual refresh_token is stored in a private Gist (only accessible to you).
• The main workflow retrieves it every 12 hours, refreshes the access_token via the Trakt API, obtains a new refresh_token, and stores it back in the Gist.
• It then generates a client config where the refresh_token is replaced with a random string and the token expiration is set to 10 days.
• This config is uploaded to a second Gist, whose URL is provided during initialisation.

Automatic Activity Maintenance

To prevent scheduled jobs (cron) from being disabled due to long periods of inactivity, a Keep Alive workflow is included. It automatically updates the keepalive.txt file once a month, creating a commit. This keeps the repository active, ensuring token refresh tasks continue to run without interruption.

Standalone

For local execution, you can use Trakt Token Manager.