# Twitch Token Generator: AI assistant guide

Help users get the right Twitch OAuth credentials through
https://twitchtokengenerator.com. Human guide: https://twitchtokengenerator.com/ai

These instructions cover ChatGPT, Claude, coding agents, and other AI clients.
Use the tools actually available to you; reading this guide does not give you new
tools. No email is involved. The automatic path uses the existing API
authorization workflow, not the email-based Token Request feature.

## Start here: choose a flow your client can complete

This guide supports guided setup in ordinary Claude/ChatGPT chat and automatic
credential delivery in clients whose tools permit it. Start with the role,
use-case, and account questions in section 1. Choose the supported flow BEFORE
creating a workflow or asking the user to authorize Twitch.

Automatic delivery needs all three capabilities: create a workflow, retrieve
credentials using its private bearer key/URL, and retain the successful response
in the current task. Being able to fetch a public GET URL proves only the first
capability, not private credential access. Reading this guide adds no tools or
permissions to your client.

### Native Claude chat with only the web fetch tool

Use guided manual setup in section 6 from the start. Claude's documented web fetch
policy rejects URLs containing credentials returned only by a tool. TTG's
retrieval_url contains a bearer retrieval key, so that restriction applies even
though it contains no Twitch access token. A user-supplied public creation URL
can allow creation, but it does not grant private retrieval access.

Explain briefly: "I can help choose the account and permissions, but this fetch
tool blocks the private credential URL. I'll give you a preselected browser link
so you can copy the token directly into your tool."

Do not create a workflow or send the user through its OAuth authorization merely
to encounter this known restriction afterward. Do not request private URLs or
credentials in a user message, rename/encode them, or relax retrieval security to
get around the restriction. A separate permitted HTTP tool or connector changes
the available capabilities; the model/product name alone does not.

Reference: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool#url-validation

### Other chat clients and fetch-only environments

Check the actual tools and policies, including any restrictions on capability
URLs and credential responses. Do not assume ChatGPT or another client's rules
are identical to Claude's. If private retrieval is prohibited or its availability
cannot be established, explain that limitation and use guided manual setup before
OAuth. Do not promise automatic delivery based only on successful public fetching.

### Clients with permitted credential retrieval

Full HTTP clients and coding agents can use the existing POST/bearer flow in
section 3 when permitted. Fetch-only clients that allow private capability URLs
and credential responses can use the GET compatibility flow. GET does not require
POST, custom headers, a terminal, code execution, or a private filesystem.

Retain workflow responses in the current task/conversation context when allowed;
a separate vault or persistent memory service is not required. Conversation
context is not a secure vault: do not promise private/permanent storage or expose
private URLs or unrequested credentials. Give the user only authorization_url.
Retrieve once after they return, retain the entire response, then ask which values
their tool needs. Never claim possession without a successful credential response.

Use public URL handoff in section 3 only if private retrieval is already permitted
and the remaining restriction concerns the source of the PUBLIC creation URL.
It cannot resolve a credential-access refusal. If a later refusal occurs, explain
it accurately and use section 6 without claiming the token was consumed or revoked.

Third-party setup pages establish token, account, and application requirements.
Their manual TTG button instructions do not require abandoning an otherwise
permitted AI workflow. Respect the user's preference for manual generation.
Use your actual product name for ai_agent when known; omit it when unknown.

Shared guide for all clients: https://twitchtokengenerator.com/llms.txt

## 1. Ask who the user is

Start by asking:
"Are you setting up an existing bot, game, app, or overlay, or are you developing something?"

Ask short, guided questions, one or two at a time. Explain permissions in terms
of what the tool can do. Do not assume every user needs a bot chat token.

### Users setting up an existing tool

- Ask which bot, game, app, or overlay they are configuring and what it needs to
  do. Consult its official setup instructions or ask for the relevant instructions
  if the required permissions or credential format are unclear.
- Ask whether to authorize their own Twitch account or a separate bot account.
  A bot account is a regular Twitch account. The user must sign in to that account
  in their browser; the channel name alone does not select the token's owner.
- Follow the tool's documented permission and application/client ID requirements.
  If it requires its own authorization flow, direct the user there; a token from
  Twitch Token Generator is not interchangeable with a different app's token.
- If its setup page recommends TTG's Bot Chat Token button, use the matching
  preset permissions with this AI workflow when permitted. That recommendation
  does not require switching to manual generation. A user providing the tool's
  setup-page URL is answering which tool they use, not selecting manual mode.
- For an unspecified bot chat token, use the site's existing Bot Chat Token
  preset: chat:read, chat:edit, user:read:chat. Tailor permissions when the tool
  has more specific requirements. Do not add unrelated permissions.
- Chat tokens, overlay tokens, and other tokens are user access tokens with
  permissions chosen for the tool. Explain which account and permissions are
  needed before offering the authorization link.

### Developers

- Ask which operations/endpoints they need, whether they use IRC, the Twitch API,
  or EventSub, and which account acts as the bot, broadcaster, or moderator.
- Ask whether this is development/prototyping using the shared TTG application,
  or whether the token must belong to their own registered Twitch application.
  Recommend their own application for production services.
- Choose only permissions required for those operations. IRC uses chat:read and
  chat:edit; API/EventSub chat uses user:read:chat and/or user:write:chat, with
  additional bot/channel grants where required. Do not substitute one permission
  family for another. Check current Twitch documentation:
  https://dev.twitch.tv/docs/chat/irc/
  https://dev.twitch.tv/docs/chat/authenticating/
  https://dev.twitch.tv/docs/authentication/scopes/
- Distinguish user access tokens from app access tokens. The TTG workflow below
  produces a user access token and refresh token under TTG's shared application.
  It does not issue app access tokens or authorize the developer's own application.
  For app access tokens, explain Twitch's client credentials flow:
  https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/
- Some features need separate bot and broadcaster authorizations or a particular
  account role. Explain the distinction and use a separate workflow for each
  required account. Permissions alone do not grant moderator/broadcaster status.
- If their own client credentials are required, use the existing website's
  "Use My Client Secret and Client ID" section instead of the API workflow.
  Have the user enter credentials in the website, register the callback URL shown
  there, and copy the resulting values themselves. Never ask for their client
  secret in chat. Do not add custom-client fields to the workflow request.

## 2. Check whether automatic retrieval is possible

Apply the capability check above before OAuth:

- Native Claude web fetch alone: guided manual setup in section 6. The private
  retrieval credential is generated in a tool result and cannot satisfy its
  documented credential-URL policy. Do not use creation as a compatibility test.
- Other clients without known permitted private credential access, no live fetch,
  or no ability to retain the response: guided manual setup with an explanation.
- Permitted full HTTP tools: existing POST creation and bearer-header retrieval.
- Permitted GET tools that allow credential responses and private capability URLs:
  GET compatibility flow, with public URL handoff only if needed.

A missing POST tool or private filesystem alone is not a reason to reject the GET
flow. Conversely, working public GET requests alone do not establish that an
agent can retrieve secrets. Do not invent tool capabilities, successful requests,
or refusals. Respect explicit restrictions on actions and credential handling.

## 3. Create an authorization workflow

Base URL: https://twitchtokengenerator.com

First GET https://twitchtokengenerator.com/api/v2/scopes.
Response: {"success":true,"scopes":[...]}.
Each scope has id (number), scope (name), description, secret (boolean), and active
(boolean). Chat/GET clients use the scope NAMES. Only POST clients need to map the
chosen names to numeric IDs. Do not hardcode IDs or use obsolete scopes. If a
specifically needed scope is absent, check GET /api/v2/scopes?include_sensitive=true;
only request it when the use case requires it and explain it to the user.

### Fetch-only clients with permitted credential access: GET

GET /api/v2/ai/workflows/create with these URL-encoded query parameters:

- scopes: the chosen scope NAMES joined with commas. Do not put numeric IDs here.
  An explicitly empty scopes= is allowed when no permissions are needed.
- ai_agent: your actual client product name when known; omit it when unknown.
- nonce: a fresh, non-secret identifier for each creation attempt, recommended to
  avoid reusing a cached creation response. It may contain at most 128 bytes.

Example for a client with permitted credential access, labelled ChatGPT and using
the site's bot chat preset:

https://twitchtokengenerator.com/api/v2/ai/workflows/create?scopes=chat%3Aread%2Cchat%3Aedit%2Cuser%3Aread%3Achat&ai_agent=ChatGPT&nonce=UNIQUE_PER_ATTEMPT

Replace the scopes and ai_agent for your actual use case and replace the nonce
with a fresh value when preparing a new creation request. Fetch that URL directly
when permitted, using the public handoff below if needed. Do not open it in the
user's browser or submit it as a search query. This creates a pending authorization
workflow, not a Twitch token. The human still authorizes in their browser.

#### Public URL handoff for compatible URL-restricted clients

Use this only after establishing that private credential retrieval is permitted.
Native Claude web fetch alone does not qualify. If a compatible tool requires URLs
to have appeared in a user message, or returns url_not_in_prior_context /
"only opens URLs that have already appeared in the conversation", follow these
steps instead of immediately choosing manual mode:

1. Explain: "My fetch tool needs you to send the public setup URL first. It
   contains the requested permissions and agent label, not a token or password."
2. Show a copyable message with the COMPLETE creation URL you prepared:

   Please fetch this public workflow-creation URL to set up my Twitch authorization: <EXACT_PUBLIC_CREATION_URL>

   Replace the placeholder with the actual URL, including its selected scopes,
   agent label, and fresh nonce. Ask the user to copy and SEND that message back
   in the conversation. Do not ask them to open the creation URL in a browser or
   paste a raw API response. Do not claim a workflow has been created yet.
3. Wait for the user's message. On that turn, fetch the EXACT URL they supplied,
   preserving its query parameters and nonce. A changed URL would need another
   handoff. A URL appearing only in your own output is not enough.
4. If creation succeeds, continue with the returned authorization_url and normal
   one-time retrieval. If the tool still refuses, explain the actual error and
   offer section 6. Do not repeatedly change URLs to evade a refusal.

This is a user-supplied PUBLIC URL source, not permission to bypass credential
checks. Never perform this handoff for a private retrieval_url, retrieval key,
access token, refresh token, or client secret. A later private-retrieval refusal
still requires the manual path.

Success is HTTP 200 with success, id, authorization_url, retrieval_url,
expires_at, and retrieval_notice. The title, AI flag, and /ai/complete success
redirect are set by the server. There is no custom redirect or client secret.

Keep the COMPLETE response in the current task/conversation context if permitted;
no local credential file or vault is required. Give the user only authorization_url.
The returned retrieval_url is a private capability URL: possession allows
one-time retrieval of the credentials after authorization. Its random secret is
stored only as a keyed hash. Treat the entire URL like a password, not a public
status link. Never publish it, cite it, put it in a search query, or send it to
anyone else. No Twitch access token or refresh token is put in the URL.

These GET responses request no caching, no indexing/archiving, and no referrer
forwarding. This cannot override an AI provider's own tool policies or internal
caches. Use a live fetch and a documented cache-bypass option when available.
Some clients, including Claude configurations, restrict which URLs can be fetched
or refuse credential-bearing URLs. If your tool refuses this private URL, stop
and use the manual path. Do not rename, base64-encode, disguise, or otherwise
obfuscate credentials to bypass the client's security checks.

### Full HTTP clients: POST

POST /api/v2/workflows with Content-Type: application/json. Use title
"Twitch Token Generator AI Assistant", the resolved numeric scope_ids array, and
redirect_url "https://twitchtokengenerator.com/ai/complete". Do not use
/api/v2/token-requests or /request/create; those are the separate email feature.

Also set is_ai:true and, if you know your client product, ai_agent to its name
(for example "ChatGPT", "Claude", "Claude Code", "Codex", or "Cursor"). Use the
actual client name, not a guessed model name; omit ai_agent when unknown. The
label is optional, at most 64 bytes, and cannot contain control characters.
These are attribution fields, not credentials or proof of the client's identity.
An explicit ai_agent takes precedence over recognizable names in the creation
request's User-Agent header. Generic curl/python/browser headers cannot identify
an AI agent and remain unknown. The browser used for Twitch login is not the AI
client. These labels are copied onto generation records for reporting; raw user
agents are not retained by this feature.

Example JavaScript using an HTTP-capable runtime (translate to your own tools as
needed). This example selects the existing bot chat preset; replace desiredScopes
with the names chosen for this user's use case:

```javascript
const base = "https://twitchtokengenerator.com";
const desiredScopes = ["chat:read", "chat:edit", "user:read:chat"];
const catalogResponse = await fetch(`${base}/api/v2/scopes`);
if (!catalogResponse.ok) throw new Error("Unable to load Twitch scopes");
const catalog = await catalogResponse.json();
if (!catalog.success) throw new Error("Unable to load Twitch scopes");
const scopeIDs = desiredScopes.map(name => {
  const scope = catalog.scopes.find(item => item.scope === name && item.active);
  if (!scope) throw new Error(`Required scope unavailable: ${name}`);
  return scope.id;
});
const createResponse = await fetch(`${base}/api/v2/workflows`, {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({
    title: "Twitch Token Generator AI Assistant",
    scope_ids: scopeIDs,
    redirect_url: `${base}/ai/complete`,
    is_ai: true
    // Also include ai_agent with your actual client name when known.
  })
});
if (createResponse.status !== 201) throw new Error("Unable to create workflow");
const workflow = await createResponse.json();
if (!workflow.success) throw new Error("Unable to create workflow");
// Retain workflow privately. Show the user only workflow.authorization_url.
```

A successful creation returns HTTP 201 and these fields:
success, id, retrieval_key, authorization_url, status_url, expires_at.

Keep retrieval_key private in your runtime. It is a separate bearer credential,
not the Twitch access token. For this POST/header flow, keep it in the
Authorization header, not in a URL. Never expose it in user-facing messages,
source code, public files, or logs. Do not print the complete creation response.

Give the user the returned authorization_url as a clickable link. Tell them:
"Open this link in your browser, sign in to the Twitch account you want to use,
and review the permissions. Authorizing allows this AI client to retrieve your
generated Twitch credentials. Then return here and tell me you've finished."

The API creator and the user's browser may use different connections/IPs. The
v2 retrieval key permits this; do not use the IP-bound legacy workflow API.
The existing workflow page displays the title and requested permissions before
the user presses "Authorize with Twitch". Do not automate their Twitch login or
ask for their Twitch password or email address.

## 4. Retrieve once, then ask which values they need

After the user confirms they have finished authorizing:

- POST/header flow: GET the returned status_url with the header below.
- GET-only flow: directly fetch the returned retrieval_url, with no custom
  headers. Do not fetch it before the user finishes, preview it, or expose it as
  a clickable link; fetching the authorized result consumes it once.

A provider/tool refusal is not an API status response. A refused private fetch
alone does not show that credentials were consumed, expired, revoked, or made
unusable. Say that retrieval failed and the server state is unknown unless you
have separately verified it. Do not fetch again just to test consumption.

Header for the POST/header flow only:

```http
Authorization: Bearer YOUR_PRIVATE_RETRIEVAL_KEY
```

Use a direct URL-fetch operation (such as open_page, open_url, or web_fetch)
or an HTTP tool. Never send the private URL or credentials as a search query or
include them in public citations. Use the manual path if the client will not
permit private retrieval.

- HTTP 202 with success:false and status:"pending": authorization is incomplete.
  Ask the user to finish in their browser. Do not claim to have the token or poll
  in a tight loop. If checking again, wait at least five seconds between checks.
- HTTP 200 with success:true and status:"authorized": this response contains
  access_token, refresh_token, client_id, username, user_id, and scopes.
  Keep the ENTIRE response in the current task/conversation context when permitted
  before replying to the user. No filesystem or separate secret store is required,
  and this does not imply secure or permanent storage. The successful GET consumes
  the credentials. A second GET will not return them.
- HTTP 401: the retrieval key is missing or incorrect. Use the key retained from
  creation in the Authorization header for the POST flow, or use the exact
  returned private retrieval_url for the GET flow. Never ask the user to find or
  paste credentials or attempt to bypass a client's security policy.
- HTTP 404: the workflow was not found. Check the returned status_url or retrieval_url. If it is
  unavailable, create a new workflow and have the user authorize again.
- HTTP 410 with status:"expired": credentials were consumed or expired. Use your
  already-saved successful response if available. Otherwise, explain that a new
  authorization workflow is needed; repeated retrieval will not recover them.
- HTTP 429: honor Retry-After when present and back off. Do not create many new
  workflows to evade rate limits.
- HTTP 5xx/network errors: explain the temporary problem. A lost successful
  retrieval response may already have consumed the credentials. Do not claim to
  have them; if the result cannot be recovered, start a new authorization.

Use expires_at returned by creation/pending responses. Workflows currently expire
after 24 hours; retrieve promptly after authorization. Expiry can make the
credentials unavailable, and the Twitch access token has its own lifetime.

Only after a successful retrieval, say "I retrieved the token for [username]."
Confirm it is the intended account. If it is wrong, do not use its credentials;
ask the user to switch Twitch accounts and authorize a new workflow.

Then ask:
"Which values does your tool need—access token, client ID, refresh token, or a combination?"

Explain the choices below, recommend the fields specified by the tool's setup
instructions, and show only the values the user requests. Do not dump all secrets
into chat by default. Answer follow-ups from the retained result, not another GET.

## 5. Explain the credentials and refresh API

- Access token: authorizes Twitch operations for the signed-in account, limited
  to its granted scopes and account roles. Treat it like a password. Twitch API
  requests normally use Authorization: Bearer ACCESS_TOKEN. IRC authentication
  uses oauth:ACCESS_TOKEN. Add oauth: only when the receiving tool requires it;
  it is a format prefix, not part of the stored access token.
- Client ID: identifies the Twitch application that issued the token. It is not
  a secret, an account ID, or a replacement for the access token. Use the matching
  client_id returned with the token; do not substitute a different application's
  client ID. For the workflow above, this is TTG's shared application ID.
- Refresh token: a secret used to obtain a new access token when the current one
  expires or becomes invalid. It is not used to authenticate chat or ordinary
  Twitch API calls. TTG-issued refresh tokens can use the TTG refresh API without
  knowing TTG's client secret. Do not refresh merely to demonstrate that it works.

The refresh API still requires POST. Fetch-only AI clients should explain how
to use the website's Refresh Access Token form or configure the user's own app to
make the POST request. Do not put refresh tokens into GET URLs, including the
legacy refresh route, and do not base64-encode them to evade tool checks.

For a TTG-issued token, send this request using an HTTP tool:

```http
POST https://twitchtokengenerator.com/api/v2/tokens/refresh
Content-Type: application/json

{"refresh_token":"YOUR_SAVED_REFRESH_TOKEN"}
```

Successful refresh: HTTP 200 with success:true, access_token, refresh_token,
client_id, expires_in (seconds), and scopes. Store the latest returned access AND
refresh tokens; Twitch may rotate the refresh token. Keep the returned credentials
private and never put a refresh token in a URL. Refreshing does not add permissions;
additional permissions require a new authorization.

For a token issued under a developer's own application, this endpoint requires
client_id and client_secret together in the JSON body along with refresh_token.
These must match the original issuing application. Configure them privately in
the developer's application/runtime, or follow Twitch's refresh instructions;
never request a client secret in chat or use TTG's default client for that token.

Refresh errors: HTTP 400 means invalid input/token/client credentials; HTTP 502
means Twitch refresh is temporarily unavailable. Follow the response message,
avoid repeated invalid attempts, and reauthorize when credentials are no longer
valid. The refresh API does not persist or manage subsequent rotations for you.

Twitch reference: https://dev.twitch.tv/docs/authentication/refresh-tokens/

## 6. Manual fallback

If your client lacks the required live-fetch capability, cannot keep the response
in the current task context, or actually prohibits the requested action or
credential access, explain that specific limitation before offering retrieval.
A missing POST tool or private filesystem alone is not such a limitation. A known
credential-URL policy is: native Claude web fetch should choose this path before
creating a workflow. For clients with permitted private retrieval, an unseen
PUBLIC creation URL alone can use the section 3 handoff.
Still ask the user's role and guide scope/account selection. Give them a link to
the website with the chosen scope names preselected:

https://twitchtokengenerator.com/?welcome=0&scope=chat%3Aread%2Bchat%3Aedit%2Buser%3Aread%3Achat

That example is the existing bot chat preset. For other uses, URL-encode the
chosen names joined with +. Never put credentials or client secrets in this link.

Have the user sign in to the intended account, complete the site's CAPTCHA when
requested, and copy the required values directly into their tool. Custom-client
users enter their own client ID and secret on the website before authorizing.
The website displays credentials once, so they must copy them before leaving.
You cannot confirm access to or possession of a token you have not retrieved.
Do not ask the user to paste secrets back into chat just to continue guidance.

## Client compatibility

Use this same guide and starting prompt in ChatGPT, Claude, and other clients.
Automatic access depends on the enabled tools and their credential policies,
not the model's name. Native Claude web fetch alone uses guided manual setup;
public GET support does not remove its credential-URL restriction.
Fetch-only clients can use the GET compatibility flow when their tools allow live
creation and private one-time retrieval. Full HTTP clients should use the POST
and bearer-header flow. Neither path overrides provider restrictions on private
URLs, credential handling, network access, or caching. Use manual generation when
the available tools cannot safely complete the selected path.

Official tool documentation:
https://developers.openai.com/api/docs/guides/tools
https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool