Dirework

Twitch Integration Setup

Complete guide to setting up Twitch OAuth, bot account, and all integrations

This guide walks you through every step of setting up Twitch integration for Dirework — from creating the Twitch application to connecting your bot account.

Overview

Dirework uses Twitch OAuth for two things:

  1. Streamer login — You sign in with your main Twitch account
  2. Bot account — A separate Twitch account that reads and sends chat messages

Both use the same Twitch application, but different redirect URLs.

Step 1: Create a Twitch Application

  1. Go to the Twitch Developer Console
  2. Log in with your main Twitch account (the streamer account)
  3. Click Applications in the left sidebar
  4. Click Register Your Application

Fill in the application details

FieldValue
NameDirework (or any name you want)
OAuth Redirect URLsSee below
CategoryBroadcasting Suite
Client TypeConfidential

Add redirect URLs

You need to add two redirect URLs. Click the + Add button for each:

For local development:

http://localhost:3001/api/auth/callback/twitch
http://localhost:3001/api/bot/callback/twitch

For production (add these too if you plan to deploy — swap in your workers.dev subdomain):

https://dirework.<your-subdomain>.workers.dev/api/auth/callback/twitch
https://dirework.<your-subdomain>.workers.dev/api/bot/callback/twitch

The redirect URLs must match exactly — including the protocol (http vs https), port number, and path. A mismatch will cause "Invalid redirect URI" errors.

  1. Click Create

Copy your credentials

After creating the app:

  1. You'll see the Client ID on the application page — copy it
  2. Click New Secret to generate a Client Secret
  3. Copy the secret immediately — it's only shown once

If you lose the client secret, you'll need to generate a new one by clicking New Secret again. This will invalidate the old secret.

Step 2: Configure Environment Variables

Create or edit your packages/infra/.env file (copy it from .env.example if you haven't yet) and add the Twitch credentials:

# Twitch OAuth (from dev.twitch.tv)
TWITCH_CLIENT_ID="paste_your_client_id_here"
TWITCH_CLIENT_SECRET="paste_your_client_secret_here"

Your complete .env should look like this:

# Better Auth
BETTER_AUTH_SECRET="generate-a-random-32-character-string"
BETTER_AUTH_URL="http://localhost:3001"
CORS_ORIGIN="http://localhost:3001"

# Twitch OAuth
TWITCH_CLIENT_ID="abc123def456..."
TWITCH_CLIENT_SECRET="xyz789..."

Generate a strong secret with:

openssl rand -base64 32

BETTER_AUTH_URL must match the origin you used in your Twitch redirect URLs. For local dev, that's http://localhost:3001.

Step 3: Sign In

  1. Start the app with bun run dev
  2. Open http://localhost:3001
  3. On a fresh install you'll land on the setup screen — click Claim with Twitch
  4. You'll be redirected to Twitch — authorize the app with your streamer account
  5. After authorizing, you'll land on the dashboard as the instance owner

If sign-in fails, check:

  • Your TWITCH_CLIENT_ID and TWITCH_CLIENT_SECRET are correct
  • The redirect URL http://localhost:3001/api/auth/callback/twitch is in your Twitch app
  • BETTER_AUTH_URL is set to http://localhost:3001

Step 4: Create a Bot Account on Twitch

The bot account is a separate Twitch account that sends messages in your chat. You cannot use the same account for both streamer login and bot.

Create the bot account

  1. Open a private/incognito browser window (so you don't get logged out of your main account)
  2. Go to twitch.tv
  3. Click Sign Up and create a new account
    • Choose a name like YourNameBot or DireworkBot
    • You'll need a different email address
  4. Complete the account setup (verify email, etc.)

Twitch allows multiple accounts. The bot account is just a regular Twitch account that Dirework uses to send chat messages.

In your main streamer account's chat, type:

/mod YourBotUsername

This prevents the bot from being rate-limited when sending messages.

Step 5: Connect the Bot Account

  1. Go to your Dirework dashboard at http://localhost:3001/dashboard
  2. Find the Bot Account card
  3. Click Connect Bot Account
  4. You'll be redirected to Twitch — sign in with the bot account (not your streamer account)
  5. Authorize the app
  6. You'll be redirected back to the dashboard with a success message

The bot will have chat:read and chat:edit permissions — enough to read messages and respond to commands.

One more thing before the bot talks: the bot runs in a token-gated browser page, not on a server. Copy the bot page URL from Dashboard → Bot and add it to OBS as a browser source (or keep it in a pinned tab). The bot listens to chat only while that page is open. See Chat Commands for the full command list.

OAuth Scopes

Dirework requests specific OAuth scopes for each connection type:

ConnectionScopesPurpose
Streamer loginopenid, user:read:emailAuthentication, profile info
Bot accountchat:read, chat:editRead chat messages, send bot responses

You don't need to configure scopes manually — Dirework requests them automatically during the OAuth flow. The scopes are minimal by design: only what's needed for the bot to read and write chat messages.

If connection fails

Common issues:

ErrorSolution
Token exchange failedCheck that http://localhost:3001/api/bot/callback/twitch is in your Twitch app's redirect URLs
Redirected to home pageMake sure you're logged in to Dirework first
No error but nothing happenedCheck the browser console and server logs for details
"Invalid redirect URI" on TwitchThe redirect URL in your Twitch app doesn't match exactly — check for trailing slashes, wrong port, or http vs https

The most common issue is a redirect URL mismatch. The URL {BETTER_AUTH_URL}/api/bot/callback/twitch must exactly match one of the redirect URLs in your Twitch Developer Console app.

Step 6: Set Up OBS Overlays

After signing in, your dashboard shows Overlay URLs:

  1. Copy the Timer Overlay URL
  2. In OBS, add a Browser Source
  3. Paste the URL as: http://localhost:3001/overlay/t/YOUR_TOKEN
  4. Set width to 400 and height to 400
  5. Check "Shutdown source when not visible"
  6. Repeat for the Task List Overlay URL

See the Overlays guide for more details.

Redirect URLs Reference

URL PatternPurposeWhen it's used
{BETTER_AUTH_URL}/api/auth/callback/twitchStreamer loginWhen you click "Sign In"
{BETTER_AUTH_URL}/api/bot/callback/twitchBot account connectionWhen you click "Connect Bot Account"

For local development, BETTER_AUTH_URL = http://localhost:3001

For production, replace with your web worker's origin (e.g., https://dirework.<your-subdomain>.workers.dev)

Who can sign in?

You don't need to configure access. Dirework is single-owner: the first Twitch account to sign in claims the instance, and after that no one else can take it over. Your instance is yours the moment you claim it.

Production Checklist

When deploying to production, make sure to:

  • Set BETTER_AUTH_URL and CORS_ORIGIN to your web worker's origin — for GitHub Actions deploys these live at the top of .github/workflows/deploy.yml
  • Add production redirect URLs to your Twitch app:
    • https://dirework.<your-subdomain>.workers.dev/api/auth/callback/twitch
    • https://dirework.<your-subdomain>.workers.dev/api/bot/callback/twitch
  • Use https:// (not http://) for all production URLs

The full walkthrough lives in the Deployment guide.

Getting Started

Run Dirework on your own computer in a few minutes

Environment Variables

All environment variables used by Dirework

On this page

OverviewStep 1: Create a Twitch ApplicationFill in the application detailsAdd redirect URLsCopy your credentialsStep 2: Configure Environment VariablesStep 3: Sign InStep 4: Create a Bot Account on TwitchCreate the bot accountMake the bot a moderator (recommended)Step 5: Connect the Bot AccountOAuth ScopesIf connection failsStep 6: Set Up OBS OverlaysRedirect URLs ReferenceWho can sign in?Production Checklist