Twitch Identity and OAuth

Twitch identity and OAuth

BlokeBot uses one Twitch application identity for dashboard sign-in, the main bot, normal channel connection, and custom-bot authorization. These flows do not all retain the same credentials.

If you have not created that application yet, start with Configure a Twitch developer application.

Application and main-bot identity

Create a Website Integration application in the Twitch Developer Console. Configure these values for BlokeBot:

Setting	Default or resolution	Notes
TwitchBot:Identity:BotUsername	Empty	Required when the runtime is active; normalized as a Twitch login
TwitchBot:Identity:ClientId	Empty	Required when active; not itself secret
TwitchBot:Identity:ClientSecret	Empty	Required when active; keep secret
TwitchBot:Identity:RedirectUri	https://localhost:7107/oauth/callback	Absolute main-bot callback URI registered with Twitch
TwitchBot:Identity:TokenCachePath	Platform state directory plus twitch.tokens.json	Explicit value overrides --data-dir for this file

Environment form:

TwitchBot__Identity__BotUsername=my-bot
TwitchBot__Identity__ClientId=public-client-id
TwitchBot__Identity__ClientSecret=private-client-secret
TwitchBot__Identity__RedirectUri=https://bot.example.com/oauth/callback

The same Twitch application must register both public HTTPS callbacks:

https://bot.example.com/auth/twitch/callback
https://bot.example.com/oauth/callback

Each callback must match exactly, including scheme, host, port, path, and any configured path base. See HTTPS and reverse proxy.

What each login stores

Flow	Durable result
Dashboard Sign in with Twitch	A BlokeBot authentication cookie; the callback access token is used for identity and access checks, not stored as a reusable OAuth token set
Channel setup Connect channel	Authorization time and granted scopes in SQLite after matching the existing channel identity; the callback token set is not retained
Admin Connect bot account	The main bot's reusable token set in twitch.tokens.json
Channel setup Connect custom bot	Access token, refresh token, and expiry protected in SQLite with automatically managed Data Protection keys

Custom-bot encryption needs no operator configuration. If BlokeBot cannot read a stored custom-bot credential, that custom bot stays disabled and the channel owner is prompted to reconnect it; BlokeBot does not silently use the main bot instead.

Scopes

Dashboard sign-in requests user:read:moderated_channels. Normal channel connection uses the configured channel scope, shipped as:

channel:bot

The shipped main/custom-bot identity scopes are:

user:read:chat
user:write:chat
user:bot
moderator:read:followers
moderator:manage:announcements
user:read:follows
user:read:moderated_channels

Scopes are normalized, sorted, and deduplicated. Scope tokens may contain ASCII letters, digits, _, and :; empty segments and doubled colons are rejected.

Dashboard callback and cookie

TwitchWebAuth contains only the web-specific callback and cookie settings:

Setting	Default
TwitchWebAuth:CallbackPath	/auth/twitch/callback
TwitchWebAuth:CookieName	BlokeBot.Auth

Dashboard OAuth reuses TwitchBot:Identity:ClientId and ClientSecret; there is no second application secret.

Disconnect and upgrade behavior

• Dashboard Log out removes the local BlokeBot session.
• Disconnect channel clears BlokeBot's stored channel-authorization metadata. The channel flow did not retain a reusable token set.
• Disconnect for the main or custom bot removes BlokeBot's locally stored grant.
• An upgrade from old plaintext custom-bot credentials deletes those credentials, disables the custom bot, and alerts the channel owner to connect it again.

See State and secrets for the database-only security boundary.