Twitch Integration Setup

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:

Streamer login — You sign in with your main Twitch account
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

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

Fill in the application details

Field	Value
Name	`Dirework` (or any name you want)
OAuth Redirect URLs	See below
Category	Broadcasting Suite
Client Type	Confidential

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

For production (add these too if you plan to deploy):

https://your-domain.com/api/auth/callback/twitch
https://your-domain.com/api/bot/callback

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

Click Create

Copy your credentials

After creating the app:

You'll see the Client ID on the application page — copy it
Click New Secret to generate a Client Secret
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 apps/web/.env file 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:

# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/dirework"

# 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..."

# Optional: restrict who can log in
ALLOWED_TWITCH_IDS=""

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.

Start the app with pnpm dev
Open http://localhost:3001
Click Sign In in the top-right corner
You'll be redirected to Twitch — authorize the app with your streamer account
After authorizing, you'll land on the dashboard

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

Open a private/incognito browser window (so you don't get logged out of your main account)
Go to twitch.tv
Click Sign Up and create a new account
- Choose a name like YourNameBot or DireworkBot
- You'll need a different email address
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.

Make the bot a moderator (recommended)

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

Go to your Dirework dashboard at http://localhost:3001/dashboard
Find the Bot Account card
Click Connect Bot Account
You'll be redirected to Twitch — sign in with the bot account (not your streamer account)
Authorize the app
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.

OAuth Scopes

Dirework requests specific OAuth scopes for each connection type:

Connection	Scopes	Purpose
Streamer login	`openid`, `user:read:email`	Authentication, profile info
Bot account	`chat:read`, `chat:edit`	Read 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:

Error	Solution
Token exchange failed	Check that `http://localhost:3001/api/bot/callback` is in your Twitch app's redirect URLs
Redirected to home page	Make sure you're logged in to Dirework first
No error but nothing happened	Check the browser console and server logs for details
"Invalid redirect URI" on Twitch	The 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 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:

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

See the Overlays guide for more details.

Redirect URLs Reference

URL Pattern	Purpose	When it's used
`{BETTER_AUTH_URL}/api/auth/callback/twitch`	Streamer login	When you click "Sign In"
`{BETTER_AUTH_URL}/api/bot/callback`	Bot account connection	When you click "Connect Bot Account"

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

For production, replace with your domain (e.g., https://dirework.example.com)

# Single user
ALLOWED_TWITCH_IDS="123456789"

# Multiple users (comma-separated)
ALLOWED_TWITCH_IDS="123456789,987654321"

# Allow everyone (leave empty or omit)
ALLOWED_TWITCH_IDS=""

Production Checklist

When deploying to production, make sure to:

Update BETTER_AUTH_URL to your production domain
Update CORS_ORIGIN to your production domain
Add production redirect URLs to your Twitch app:
- https://your-domain.com/api/auth/callback/twitch
- https://your-domain.com/api/bot/callback
Use https:// (not http://) for all production URLs
Set ALLOWED_TWITCH_IDS to restrict access if needed