API documentation
Build Twitch authorization workflows, inspect permissions, and manage tokens with the v2 API.
Authorization workflow
- Read the scope catalog and choose the active scope IDs your integration needs.
- Create a workflow. Keep its retrieval key private and open authorization_url in the account owner’s browser.
- After authorization, retrieve the credentials once. Save both the access token and the latest refresh token.
Workflows expire after 24 hours. A successful retrieval consumes the stored credentials. Wait at least five seconds between pending checks.
Authentication and limits
Workflow retrieval uses its own private key as a Bearer credential. Other endpoints use the inputs shown below. The v2 API allows 180 requests per minute per IP; HTTP 429 means the limit was reached.
Endpoint reference
GET /api/v2/scopes
Available Token Scopes
Read current scope IDs, names, descriptions, and availability. This request needs no credentials.
Parameters
include_sensitiveOptionalboolean· queryInclude scopes marked sensitive in the catalog.
Response
HTTP 200- Successful response
application/jsonExample response
{ "scopes": [ { "active": true, "api_set": "helix", "description": "View live Stream Chat and Rooms messages.", "id": 28, "scope": "chat:read", "secret": false } ], "success": true } HTTP 429- Rate limit reached
application/jsonExample response
{ "message": "rate limit exceeded", "success": false } HTTP 503- Service temporarily unavailable
application/jsonExample response
{ "message": "service temporarily unavailable", "success": false }
POST /api/v2/workflows
Create an authorization workflow
Creates a 24-hour workflow under TTG’s shared Twitch application. The response separates the public authorization URL from the private retrieval key.
Parameters
ai_agentOptionalstring· bodyOptional AI client name, up to 64 UTF-8 bytes without control characters. This is attribution, not authentication.
is_aiOptionalboolean· bodyMark a workflow as AI-assisted.
redirect_urlOptionalstring· bodyOptional absolute HTTP or HTTPS destination after authorization. URL credentials are not allowed.
scope_idsOptionalarray· bodyNumeric IDs from the scope catalog. Choose active scopes; at most 150 distinct scopes.
titleOptionalstring· bodyApplication name, up to 500 UTF-8 bytes.
JSON request body
{
"scope_ids": [
28,
29
],
"title": "Example integration"
}
Response
HTTP 201- Created
application/jsonExample response
{ "authorization_url": "https://twitchtokengenerator.com/api/example0000000000000", "expires_at": "2030-01-01T12:00:00Z", "id": "example0000000000000", "retrieval_key": "example000000000000000000000000000000000", "status_url": "https://twitchtokengenerator.com/api/v2/workflows/example0000000000000", "success": true } HTTP 400- Invalid request
application/jsonExample response
{ "message": "invalid request", "success": false } HTTP 429- Rate limit reached
application/jsonExample response
{ "message": "rate limit exceeded", "success": false } HTTP 500- The request could not be processed
application/jsonExample response
{ "message": "unable to process request", "success": false }
GET /api/v2/workflows/{id}
Retrieve workflow credentials
Returns credentials once after authorization. Send the workflow retrieval key as a Bearer credential. A successful read consumes the stored credentials.
Parameters
idRequiredstring· pathThe workflow ID returned when it was created.
AuthorizationRequiredBearer· headerThe private retrieval key returned when the workflow was created. Keep it out of public links.
Response
HTTP 200- Successful response
application/jsonExample response
{ "access_token": "EXAMPLE_ACCESS_TOKEN", "client_id": "EXAMPLE_CLIENT_ID", "refresh_token": "EXAMPLE_REFRESH_TOKEN", "scopes": [ "chat:read", "chat:edit" ], "status": "authorized", "success": true, "user_id": "123456789", "username": "exampleuser" } HTTP 202- Authorization is still pending
application/jsonExample response
{ "expires_at": "2030-01-01T12:00:00Z", "status": "pending", "success": false } HTTP 401- Invalid token or retrieval key
application/jsonExample response
{ "message": "invalid retrieval key", "success": false } HTTP 404- Workflow not found
application/jsonExample response
{ "message": "workflow not found", "success": false } HTTP 410- Credentials expired or already retrieved
application/jsonExample response
{ "message": "workflow credentials are no longer available", "status": "expired", "success": false } HTTP 429- Rate limit reached
application/jsonExample response
{ "message": "rate limit exceeded", "success": false } HTTP 500- The request could not be processed
application/jsonExample response
{ "message": "unable to process request", "success": false } HTTP 503- Service temporarily unavailable
application/jsonExample response
{ "message": "service temporarily unavailable", "success": false }
GET /api/v2/ai/workflows/create
Create a fetch-only AI workflow
GET alternative for fetch-only clients. Creates a workflow using scope names and returns a private retrieval URL. The JSON response is served as text/plain.
Parameters
scopesRequiredstring· queryComma-separated scope names. The parameter must be present; an empty value requests no scopes.
ai_agentOptionalstring· queryOptional AI client name, up to 64 UTF-8 bytes without control characters. This is attribution, not authentication.
nonceOptionalstring· queryOptional cache-busting value, up to 128 UTF-8 bytes. It is not an idempotency key.
Response
HTTP 200- Successful response
text/plainExample response
{ "authorization_url": "https://twitchtokengenerator.com/api/example0000000000000", "expires_at": "2030-01-01T12:00:00Z", "id": "example0000000000000", "retrieval_notice": "Keep retrieval_url private: it grants one-time access to the generated credentials. Give the user only authorization_url. Retrieve after they finish authorizing.", "retrieval_url": "https://twitchtokengenerator.com/api/v2/ai/workflows/example0000000000000/example000000000000000000000000000000000", "success": true } HTTP 400- Invalid request
text/plainExample response
{ "message": "invalid request", "success": false } HTTP 429- Rate limit reached
text/plainExample response
{ "message": "rate limit exceeded", "success": false } HTTP 500- The request could not be processed
text/plainExample response
{ "message": "unable to process request", "success": false }
GET /api/v2/ai/workflows/{id}/{key}
Retrieve fetch-only AI credentials
GET alternative with the retrieval key in the URL. The JSON response is served as text/plain. A successful read consumes the stored credentials.
Parameters
idRequiredstring· pathThe workflow ID returned when it was created.
keyRequiredstring· pathThe private retrieval key returned when the workflow was created. Keep it out of public links.
Response
HTTP 200- Successful response
text/plainExample response
{ "access_token": "EXAMPLE_ACCESS_TOKEN", "client_id": "EXAMPLE_CLIENT_ID", "refresh_token": "EXAMPLE_REFRESH_TOKEN", "scopes": [ "chat:read", "chat:edit" ], "status": "authorized", "success": true, "user_id": "123456789", "username": "exampleuser" } HTTP 202- Authorization is still pending
text/plainExample response
{ "expires_at": "2030-01-01T12:00:00Z", "status": "pending", "success": false } HTTP 401- Invalid token or retrieval key
text/plainExample response
{ "message": "invalid retrieval key", "success": false } HTTP 404- Workflow not found
text/plainExample response
{ "message": "workflow not found", "success": false } HTTP 410- Credentials expired or already retrieved
text/plainExample response
{ "message": "workflow credentials are no longer available", "status": "expired", "success": false } HTTP 429- Rate limit reached
text/plainExample response
{ "message": "rate limit exceeded", "success": false } HTTP 500- The request could not be processed
text/plainExample response
{ "message": "unable to process request", "success": false } HTTP 503- Service temporarily unavailable
text/plainExample response
{ "message": "service temporarily unavailable", "success": false }
POST /api/v2/tokens/refresh
Refresh Access Token
Renews an access token using a refresh token. Supply both client_id and client_secret when refreshing a token from your own Twitch application.
Parameters
client_idOptionalstring· bodyTwitch application client ID. Omit it to use TTG’s shared application.
client_secretOptionalstring· bodyTwitch application client secret. For refresh requests, provide it together with client_id.
refresh_tokenRequiredstring· bodyThe latest refresh token for the account and Twitch application.
JSON request body
{
"refresh_token": "EXAMPLE_REFRESH_TOKEN"
}
Response
HTTP 200- Successful response
application/jsonExample response
{ "access_token": "EXAMPLE_ACCESS_TOKEN", "client_id": "EXAMPLE_CLIENT_ID", "expires_in": 3600, "refresh_token": "EXAMPLE_REFRESH_TOKEN", "scopes": [ "chat:read", "chat:edit" ], "success": true } HTTP 400- Invalid request
application/jsonExample response
{ "message": "invalid request", "success": false } HTTP 429- Rate limit reached
application/jsonExample response
{ "message": "rate limit exceeded", "success": false } HTTP 502- Twitch request failed
application/jsonExample response
{ "message": "Twitch request failed", "success": false }
POST /api/v2/tokens/revoke
Revoke Your Access Token
Invalidates the supplied access token. Supply its application’s client_id if it differs from TTG’s shared application.
Parameters
access_tokenRequiredstring· bodyThe Twitch access token to inspect or revoke, without an oauth: prefix.
client_idOptionalstring· bodyTwitch application client ID. Omit it to use TTG’s shared application.
JSON request body
{
"access_token": "EXAMPLE_ACCESS_TOKEN"
}
Response
HTTP 200- Successful response
application/jsonExample response
{ "success": true } HTTP 400- Invalid request
application/jsonExample response
{ "message": "invalid request", "success": false } HTTP 429- Rate limit reached
application/jsonExample response
{ "message": "rate limit exceeded", "success": false } HTTP 502- Twitch request failed
application/jsonExample response
{ "message": "Twitch request failed", "success": false }
POST /api/v2/tokens/validate
Validate a token
Inspects the token’s account, application, granted permissions, and remaining lifetime.
Parameters
access_tokenRequiredstring· bodyThe Twitch access token to inspect or revoke, without an oauth: prefix.
JSON request body
{
"access_token": "EXAMPLE_ACCESS_TOKEN"
}
Response
HTTP 200- Successful response
application/jsonExample response
{ "client_id": "EXAMPLE_CLIENT_ID", "expires_in": 3600, "scope_details": [ { "active": true, "api_set": "helix", "description": "View live Stream Chat and Rooms messages.", "id": 28, "scope": "chat:read", "secret": false } ], "scopes": [ "chat:read" ], "success": true, "user_id": "123456789", "username": "exampleuser" } HTTP 400- Invalid request
application/jsonExample response
{ "message": "invalid request", "success": false } HTTP 401- Invalid token or retrieval key
application/jsonExample response
{ "message": "invalid retrieval key", "success": false } HTTP 429- Rate limit reached
application/jsonExample response
{ "message": "rate limit exceeded", "success": false } HTTP 502- Twitch request failed
application/jsonExample response
{ "message": "Twitch request failed", "success": false }
POST /api/v2/quick-links
Quick Link Generator
Creates a reusable link with selected scope IDs. auth=stay opens the generator; auth=authorize starts Twitch authorization.
Parameters
authOptionalstring· bodystay opens the generator. authorize and the compatibility alias auth_auth begin authorization immediately.
scope_idsOptionalarray· bodyNumeric IDs from the scope catalog. Choose active scopes; at most 150 distinct scopes.
JSON request body
{
"auth": "stay",
"scope_ids": [
28,
29
]
}
Response
HTTP 201- Created
application/jsonExample response
{ "id": "example000", "success": true, "url": "https://twitchtokengenerator.com/quick/example000" } HTTP 400- Invalid request
application/jsonExample response
{ "message": "invalid request", "success": false } HTTP 429- Rate limit reached
application/jsonExample response
{ "message": "rate limit exceeded", "success": false } HTTP 500- The request could not be processed
application/jsonExample response
{ "message": "unable to process request", "success": false }
POST /api/v2/token-requests
Request Token From User
Creates an authorization request link. After the account owner completes authorization, credentials are sent to my_email.
Parameters
my_emailRequiredstring· bodyEmail address that receives credentials after the request is completed.
my_nameRequiredstring· bodyRequester name, up to 128 UTF-8 bytes.
scope_idsOptionalarray· bodyNumeric IDs from the scope catalog. Choose active scopes; at most 150 distinct scopes.
JSON request body
{
"my_email": "developer@example.com",
"my_name": "Example developer",
"scope_ids": [
28,
29
]
}
Response
HTTP 201- Created
application/jsonExample response
{ "id": "example-request", "success": true, "url": "https://twitchtokengenerator.com/request/example-request" } HTTP 400- Invalid request
application/jsonExample response
{ "message": "invalid request", "success": false } HTTP 429- Rate limit reached
application/jsonExample response
{ "message": "rate limit exceeded", "success": false }
Legacy compatibility
Existing /api/ routes remain supported. Use the v2 endpoints for new integrations; their response formats and retrieval authentication differ.
| Legacy route | v2 replacement |
|---|---|
GET /api/scopes/{type} | GET /api/v2/scopes |
GET /api/create/{title}/{scopes} | POST /api/v2/workflows |
GET /api/status/{id} | GET /api/v2/workflows/{id} |
GET /api/forgot/{token} | POST /api/v2/tokens/validate |
GET /api/refresh/{token} | POST /api/v2/tokens/refresh |
GET /api/revoke/{token} | POST /api/v2/tokens/revoke |