API documentation

Build Twitch authorization workflows, inspect permissions, and manage tokens with the v2 API.

Download OpenAPI

Authorization workflow

  1. Read the scope catalog and choose the active scope IDs your integration needs.
  2. Create a workflow. Keep its retrieval key private and open authorization_url in the account owner’s browser.
  3. 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_sensitiveOptional

boolean · query

Include scopes marked sensitive in the catalog.

Response

HTTP 200
Successful response
application/json
Example 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/json
Example response
{
  "message": "rate limit exceeded",
  "success": false
}
HTTP 503
Service temporarily unavailable
application/json
Example response
{
  "message": "service temporarily unavailable",
  "success": false
}
Try this endpoint
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_agentOptional

string · body

Optional AI client name, up to 64 UTF-8 bytes without control characters. This is attribution, not authentication.

is_aiOptional

boolean · body

Mark a workflow as AI-assisted.

redirect_urlOptional

string · body

Optional absolute HTTP or HTTPS destination after authorization. URL credentials are not allowed.

scope_idsOptional

array · body

Numeric IDs from the scope catalog. Choose active scopes; at most 150 distinct scopes.

titleOptional

string · body

Application name, up to 500 UTF-8 bytes.

JSON request body

{
  "scope_ids": [
    28,
    29
  ],
  "title": "Example integration"
}

Response

HTTP 201
Created
application/json
Example 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/json
Example response
{
  "message": "invalid request",
  "success": false
}
HTTP 429
Rate limit reached
application/json
Example response
{
  "message": "rate limit exceeded",
  "success": false
}
HTTP 500
The request could not be processed
application/json
Example response
{
  "message": "unable to process request",
  "success": false
}
Try this endpoint
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

idRequired

string · path

The workflow ID returned when it was created.

AuthorizationRequired

Bearer · header

The private retrieval key returned when the workflow was created. Keep it out of public links.

Response

HTTP 200
Successful response
application/json
Example 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/json
Example response
{
  "expires_at": "2030-01-01T12:00:00Z",
  "status": "pending",
  "success": false
}
HTTP 401
Invalid token or retrieval key
application/json
Example response
{
  "message": "invalid retrieval key",
  "success": false
}
HTTP 404
Workflow not found
application/json
Example response
{
  "message": "workflow not found",
  "success": false
}
HTTP 410
Credentials expired or already retrieved
application/json
Example response
{
  "message": "workflow credentials are no longer available",
  "status": "expired",
  "success": false
}
HTTP 429
Rate limit reached
application/json
Example response
{
  "message": "rate limit exceeded",
  "success": false
}
HTTP 500
The request could not be processed
application/json
Example response
{
  "message": "unable to process request",
  "success": false
}
HTTP 503
Service temporarily unavailable
application/json
Example response
{
  "message": "service temporarily unavailable",
  "success": false
}
Try this endpoint
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

scopesRequired

string · query

Comma-separated scope names. The parameter must be present; an empty value requests no scopes.

ai_agentOptional

string · query

Optional AI client name, up to 64 UTF-8 bytes without control characters. This is attribution, not authentication.

nonceOptional

string · query

Optional cache-busting value, up to 128 UTF-8 bytes. It is not an idempotency key.

Response

HTTP 200
Successful response
text/plain
Example 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/plain
Example response
{
  "message": "invalid request",
  "success": false
}
HTTP 429
Rate limit reached
text/plain
Example response
{
  "message": "rate limit exceeded",
  "success": false
}
HTTP 500
The request could not be processed
text/plain
Example response
{
  "message": "unable to process request",
  "success": false
}
Try this endpoint
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

idRequired

string · path

The workflow ID returned when it was created.

keyRequired

string · path

The private retrieval key returned when the workflow was created. Keep it out of public links.

Response

HTTP 200
Successful response
text/plain
Example 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/plain
Example response
{
  "expires_at": "2030-01-01T12:00:00Z",
  "status": "pending",
  "success": false
}
HTTP 401
Invalid token or retrieval key
text/plain
Example response
{
  "message": "invalid retrieval key",
  "success": false
}
HTTP 404
Workflow not found
text/plain
Example response
{
  "message": "workflow not found",
  "success": false
}
HTTP 410
Credentials expired or already retrieved
text/plain
Example response
{
  "message": "workflow credentials are no longer available",
  "status": "expired",
  "success": false
}
HTTP 429
Rate limit reached
text/plain
Example response
{
  "message": "rate limit exceeded",
  "success": false
}
HTTP 500
The request could not be processed
text/plain
Example response
{
  "message": "unable to process request",
  "success": false
}
HTTP 503
Service temporarily unavailable
text/plain
Example response
{
  "message": "service temporarily unavailable",
  "success": false
}
Try this endpoint
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_idOptional

string · body

Twitch application client ID. Omit it to use TTG’s shared application.

client_secretOptional

string · body

Twitch application client secret. For refresh requests, provide it together with client_id.

refresh_tokenRequired

string · body

The latest refresh token for the account and Twitch application.

JSON request body

{
  "refresh_token": "EXAMPLE_REFRESH_TOKEN"
}

Response

HTTP 200
Successful response
application/json
Example 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/json
Example response
{
  "message": "invalid request",
  "success": false
}
HTTP 429
Rate limit reached
application/json
Example response
{
  "message": "rate limit exceeded",
  "success": false
}
HTTP 502
Twitch request failed
application/json
Example response
{
  "message": "Twitch request failed",
  "success": false
}
Try this endpoint
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_tokenRequired

string · body

The Twitch access token to inspect or revoke, without an oauth: prefix.

client_idOptional

string · body

Twitch 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/json
Example response
{
  "success": true
}
HTTP 400
Invalid request
application/json
Example response
{
  "message": "invalid request",
  "success": false
}
HTTP 429
Rate limit reached
application/json
Example response
{
  "message": "rate limit exceeded",
  "success": false
}
HTTP 502
Twitch request failed
application/json
Example response
{
  "message": "Twitch request failed",
  "success": false
}
Try this endpoint
POST /api/v2/tokens/validate

Validate a token

Inspects the token’s account, application, granted permissions, and remaining lifetime.

Parameters

access_tokenRequired

string · body

The 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/json
Example 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/json
Example response
{
  "message": "invalid request",
  "success": false
}
HTTP 401
Invalid token or retrieval key
application/json
Example response
{
  "message": "invalid retrieval key",
  "success": false
}
HTTP 429
Rate limit reached
application/json
Example response
{
  "message": "rate limit exceeded",
  "success": false
}
HTTP 502
Twitch request failed
application/json
Example response
{
  "message": "Twitch request failed",
  "success": false
}
Try this endpoint
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_emailRequired

string · body

Email address that receives credentials after the request is completed.

my_nameRequired

string · body

Requester name, up to 128 UTF-8 bytes.

scope_idsOptional

array · body

Numeric 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/json
Example response
{
  "id": "example-request",
  "success": true,
  "url": "https://twitchtokengenerator.com/request/example-request"
}
HTTP 400
Invalid request
application/json
Example response
{
  "message": "invalid request",
  "success": false
}
HTTP 429
Rate limit reached
application/json
Example response
{
  "message": "rate limit exceeded",
  "success": false
}
Try this endpoint

Legacy compatibility

Existing /api/ routes remain supported. Use the v2 endpoints for new integrations; their response formats and retrieval authentication differ.

Legacy routev2 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