Twitch API Guide: OAuth 2.0, Endpoints, Scopes, and Rate Limits

When building applications for Twitch, understanding the Twitch API is essential for automating your streaming workflow. This Twitch API guide will help you set up and understand the Twitch API structure, authentication flows, and available endpoints. The Twitch API offers a comprehensive interface for developers to interact with channels, chat, moderation, livestreams, clips, and more. This Twitch API guide focuses on the official Twitch Developer API and its OAuth 2.0 authentication system.

This Twitch API guide provides a simplified overview of the Twitch API. If you are looking for automated content reposting across platforms, check out Repostit.io for a streamlined automation solution.

Twitch API Guide: OAuth 2.0 Authentication

The Twitch API uses OAuth 2.0 for authentication, providing a secure authorization framework. As covered in this Twitch API guide, the OAuth server is hosted at https://id.twitch.tv, which is separate from the main Twitch API server at https://api.twitch.tv. Understanding the difference between these servers is crucial for implementing Twitch API authentication correctly.

Twitch API Guide: Token Types

As explained in this Twitch API guide, there are two types of access tokens, each designed for different use cases:

Token Type	OAuth Flow	Use Case	Access Level
App Access Token	Client Credentials	Server-to-server API calls without user login	Public data only
User Access Token	Authorization Code Grant	Access user data and act on behalf of users	Based on granted scopes

App Access Tokens are generated through the Client Credentials flow. These server-to-server tokens are the most basic form of API access, allowing you to retrieve publicly available data without requiring user login. They are ideal for displaying public stream information, game listings, or user profiles.

User Access Tokens are generated through the Authorization Code Grant flow. These tokens provide access to user-specific information based on the scopes your application has requested. With appropriate scopes, your application can act on the user’s behalf, such as sending chat messages, managing channel settings, or creating clips.

Twitch API Guide: Authorization Code Flow

For User Access Tokens, this Twitch API guide covers the Authorization Code flow, which provides secure authorization for applications. Here is the step-by-step process for Twitch API authentication:

1. Register your app: Create an application on the Twitch Developer Console and copy your Client ID and Client Secret.
2. Set OAuth Redirect URLs: Configure your redirect URI (e.g., http://localhost:3000 for development).
3. Set up a callback receiver: Run a local HTTP server to catch the redirect and read the code query parameter.
4. Direct user to authorize: Open the Twitch authorization URL in the browser with your parameters.

GET https://id.twitch.tv/oauth2/authorize?
    response_type=code&
    client_id=YOUR_CLIENT_ID&
    redirect_uri=http://localhost:3000&
    scope=user:read:email channel:read:subscriptions&
    state=RANDOM_STATE_VALUE

5. User approves access: The user logs in to Twitch and approves your application’s requested scopes.
6. Capture the authorization code: After consent, Twitch redirects to your URI with ?code=AUTH_CODE&state=....
7. Exchange code for tokens: Send the authorization code along with your credentials to the token endpoint.
8. Store and use tokens: Securely store the access and refresh tokens. Use Authorization: Bearer <access_token> and Client-Id: <client_id> in API requests.

Twitch API Guide: Token Exchange Example

After receiving the authorization code, this Twitch API guide shows how to exchange it for access and refresh tokens:

POST https://id.twitch.tv/oauth2/token

Headers:
Content-Type: application/x-www-form-urlencoded

Body:
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
code=AUTHORIZATION_CODE
grant_type=authorization_code
redirect_uri=http://localhost:3000

The response will contain your tokens:

{
  "access_token": "jostpf5q0puzmxmkba9iyug38kjtg",
  "expires_in": 14346,
  "refresh_token": "eyJfMzUtNDU0OC4MWYwLTQ5MDY5ODY4NGNlMSJ9%asdf=",
  "scope": ["user:read:email", "channel:read:subscriptions"],
  "token_type": "bearer"
}

Twitch API Guide: App Access Token (Client Credentials)

For server-to-server requests that only need public data, this Twitch API guide recommends the Client Credentials flow to obtain an App Access Token:

POST https://id.twitch.tv/oauth2/token

Headers:
Content-Type: application/x-www-form-urlencoded

Body:
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
grant_type=client_credentials

Response:

{
  "access_token": "jostpf5q0puzmxmkba9iyug38kjtg",
  "expires_in": 5011271,
  "token_type": "bearer"
}

Twitch API Guide: Available Scopes

Scopes define the level of access your application requests from users. This Twitch API guide lists the commonly used scopes that grant permission to specific endpoints and actions:

Scope	Description
user:read:email	View user email address
user:read:subscriptions	View user’s channel subscriptions
channel:read:subscriptions	View broadcaster’s subscribers
channel:manage:broadcast	Manage channel broadcast settings (title, game, tags)
channel:manage:polls	Create and manage channel polls
channel:manage:predictions	Create and manage channel predictions
channel:manage:raids	Start and cancel raids
channel:manage:schedule	Manage channel streaming schedule
channel:manage:videos	Delete videos from the channel
clips:edit	Create clips from broadcasts
moderation:read	View moderation data (banned users, moderators)
moderator:manage:banned_users	Ban and unban users in chat
moderator:manage:chat_messages	Delete chat messages
chat:edit	Send chat messages
chat:read	View chat messages

Twitch API Guide: Endpoints Overview

The Twitch API is hosted at https://api.twitch.tv/helix and provides endpoints for various platform features. All requests require authentication via Bearer token and Client ID. This Twitch API guide covers the main endpoint categories below:

Twitch API Guide: Users Endpoint

The Users endpoint retrieves user information based on provided user IDs or login names. If no parameters are specified with a user access token, the API returns information for the authenticated user.

Endpoint	Method	Required Scope	Description
/helix/users	GET	user:read:email (for email)	Get user information by ID or login

Example request:

GET https://api.twitch.tv/helix/users?login=twitchdev

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID

Example response:

{
  "data": [
    {
      "id": "141981764",
      "login": "twitchdev",
      "display_name": "TwitchDev",
      "type": "",
      "broadcaster_type": "partner",
      "description": "Supporting third-party developers building Twitch integrations.",
      "profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/8a6381c7-d0c0-4576-b179-38bd5ce1d6af-profile_image-300x300.png",
      "offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/3f13ab61-ec78-4fe6-8481-8682cb3b0ac2-channel_offline_image-1920x1080.png",
      "view_count": 6652509,
      "created_at": "2021-07-30T20:32:28Z"
    }
  ]
}

Twitch API Guide: Channels Endpoint

The Channels endpoint lets you retrieve and update channel information including stream title, game, and tags.

Endpoint	Method	Required Scope	Description
/helix/channels	GET	None	Get channel information by broadcaster ID
/helix/channels	PATCH	channel:manage:broadcast	Update channel information (title, game, tags)

Example GET request:

GET https://api.twitch.tv/helix/channels?broadcaster_id=141981764

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID

Example PATCH request to update channel:

PATCH https://api.twitch.tv/helix/channels?broadcaster_id=141981764

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID
Content-Type: application/json

Body:
{
  "game_id": "33214",
  "title": "Playing Fortnite with viewers!",
  "tags": ["English", "Competitive"]
}

Twitch API Guide: Streams Endpoint

The Streams endpoint retrieves information about active livestreams across the platform.

Endpoint	Method	Description
/helix/streams	GET	Get active streams filtered by user, game, or language
/helix/streams/markers	POST	Create a stream marker
/helix/streams/markers	GET	Get stream markers

Example request with filters:

GET https://api.twitch.tv/helix/streams?game_id=21779&language=en&first=20

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID

Example response:

{
  "data": [
    {
      "id": "123456789",
      "user_id": "98765",
      "user_login": "sandysanderman",
      "user_name": "SandySanderman",
      "game_id": "21779",
      "game_name": "League of Legends",
      "type": "live",
      "title": "Ranked grind to Challenger!",
      "viewer_count": 1500,
      "started_at": "2026-02-03T10:00:00Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_sandysanderman-{width}x{height}.jpg",
      "is_mature": false
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6Ik1qQT0ifX0"
  }
}

Twitch API Guide: Games/Categories Endpoint

The Games endpoint retrieves game and category information for streams.

Endpoint	Method	Description
/helix/games	GET	Get games by ID or name
/helix/games/top	GET	Get top games by viewer count
/helix/search/categories	GET	Search for categories by name

Example request:

GET https://api.twitch.tv/helix/games?name=Fortnite

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID

Example response:

{
  "data": [
    {
      "id": "33214",
      "name": "Fortnite",
      "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/33214-{width}x{height}.jpg",
      "igdb_id": "1905"
    }
  ]
}

Twitch API Guide: Clips Endpoint

The Clips endpoint allows you to create and retrieve clips from broadcasts.

Endpoint	Method	Required Scope	Description
/helix/clips	POST	clips:edit	Create a clip from a live broadcast
/helix/clips	GET	None	Get clips by broadcaster, game, or clip ID

Example POST request to create a clip:

POST https://api.twitch.tv/helix/clips?broadcaster_id=123456

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID

Example response:

{
  "data": [
    {
      "id": "FunPoisedGiraffeGingerPower-KDy2fwLNuUEHU",
      "edit_url": "https://clips.twitch.tv/FunPoisedGiraffeGingerPower-KDy2fwLNuUEHU/edit"
    }
  ]
}

Creating a clip is an asynchronous process. Use the Get Clips endpoint with the returned ID to verify the clip was created successfully. The API captures up to 90 seconds of the stream around the point when you called the API.

Twitch API Guide: Videos Endpoint

The Videos endpoint retrieves and manages VODs, highlights, and uploads.

Endpoint	Method	Required Scope	Description
/helix/videos	GET	None	Get videos by ID, user, or game
/helix/videos	DELETE	channel:manage:videos	Delete one or more videos

Example request:

GET https://api.twitch.tv/helix/videos?user_id=123456&type=archive&first=10

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID

The type parameter filters by video type: archive for VODs, highlight for highlights, or upload for uploaded videos.

Twitch API Guide: Polls Endpoint

The Polls endpoint allows broadcasters to create and manage polls for viewer engagement. Polls are available to partners and affiliates only.

Endpoint	Method	Required Scope	Description
/helix/polls	GET	channel:read:polls	Get polls for a channel
/helix/polls	POST	channel:manage:polls	Create a poll
/helix/polls	PATCH	channel:manage:polls	End a poll

Example POST request to create a poll:

POST https://api.twitch.tv/helix/polls

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID
Content-Type: application/json

Body:
{
  "broadcaster_id": "123456",
  "title": "Which game should I play next?",
  "choices": [
    {"title": "Minecraft"},
    {"title": "Fortnite"},
    {"title": "Valorant"}
  ],
  "duration": 300,
  "channel_points_voting_enabled": true,
  "channel_points_per_vote": 100
}

Twitch API Guide: Predictions Endpoint

The Predictions endpoint allows broadcasters to create predictions where viewers wager Channel Points on outcomes. Predictions are available to partners and affiliates only.

Endpoint	Method	Required Scope	Description
/helix/predictions	GET	channel:read:predictions	Get predictions for a channel
/helix/predictions	POST	channel:manage:predictions	Create a prediction
/helix/predictions	PATCH	channel:manage:predictions	End a prediction (resolve, cancel, or lock)

Example POST request to create a prediction:

POST https://api.twitch.tv/helix/predictions

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID
Content-Type: application/json

Body:
{
  "broadcaster_id": "123456",
  "title": "Will I win this match?",
  "outcomes": [
    {"title": "Yes"},
    {"title": "No"}
  ],
  "prediction_window": 120
}

Twitch API Guide: Raids Endpoint

The Raids endpoint allows broadcasters to start and cancel raids to other channels.

Endpoint	Method	Required Scope	Description
/helix/raids	POST	channel:manage:raids	Start a raid to another channel
/helix/raids	DELETE	channel:manage:raids	Cancel a pending raid

Example POST request to start a raid:

POST https://api.twitch.tv/helix/raids?from_broadcaster_id=12345678&to_broadcaster_id=87654321

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID

The request queues the raid. The raid occurs when the broadcaster clicks “Raid Now” or after the 90-second countdown expires. You can cancel a raid before it starts using the DELETE endpoint.

Twitch API Guide: Schedule Endpoint

The Schedule endpoint allows broadcasters to manage their streaming schedule with recurring and one-time segments.

Endpoint	Method	Required Scope	Description
/helix/schedule	GET	None	Get channel streaming schedule
/helix/schedule/settings	PATCH	channel:manage:schedule	Update schedule settings (vacation)
/helix/schedule/segment	POST	channel:manage:schedule	Create a schedule segment
/helix/schedule/segment	PATCH	channel:manage:schedule	Update a schedule segment
/helix/schedule/segment	DELETE	channel:manage:schedule	Delete a schedule segment

Twitch API Guide: Creator Goals Endpoint

The Creator Goals endpoint retrieves active goals that broadcasters create to rally their community.

Endpoint	Method	Required Scope	Description
/helix/goals	GET	channel:read:goals	Get broadcaster’s active creator goals

Example request:

GET https://api.twitch.tv/helix/goals?broadcaster_id=141981764

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN
Client-Id: YOUR_CLIENT_ID

Example response:

{
  "data": [
    {
      "id": "1woowvbkiNv8BRxEWSqmQz6Zk92",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "type": "follower",
      "description": "Follow goal for community growth",
      "current_amount": 27062,
      "target_amount": 30000,
      "created_at": "2021-08-16T17:22:23Z"
    }
  ]
}

Twitch API Guide: Token Management

Twitch API Guide: Refreshing Tokens

Access tokens expire after a set period. This Twitch API guide shows how to use the refresh token to obtain new tokens without requiring user re-authorization:

POST https://id.twitch.tv/oauth2/token

Headers:
Content-Type: application/x-www-form-urlencoded

Body:
grant_type=refresh_token
refresh_token=YOUR_REFRESH_TOKEN
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Twitch API Guide: Revoking Tokens

When a user logs out or you need to invalidate tokens:

POST https://id.twitch.tv/oauth2/revoke

Headers:
Content-Type: application/x-www-form-urlencoded

Body:
client_id=YOUR_CLIENT_ID
token=YOUR_ACCESS_TOKEN

Twitch API Guide: Validating Tokens

Check if a token is valid and get information about it:

GET https://id.twitch.tv/oauth2/validate

Headers:
Authorization: OAuth YOUR_ACCESS_TOKEN

Response:

{
  "client_id": "wbmytr93xzw8zbg0p1izqyzzc5mbiz",
  "login": "twitchdev",
  "scopes": ["user:read:email", "channel:read:subscriptions"],
  "user_id": "141981764",
  "expires_in": 5520838
}

Twitch API Guide: Rate Limits

The Twitch API uses a token-bucket algorithm to enforce rate limits. Your app is given a bucket of points, and each endpoint request costs points. If your bucket runs out of points within 1 minute, the API returns HTTP status code 429 (Too Many Requests). This Twitch API guide recommends monitoring rate limit headers carefully.

The API includes the following headers with each response to help you track your usage:

Header	Description
Ratelimit-Limit	The rate at which points are added to your bucket
Ratelimit-Remaining	The number of points remaining in your bucket
Ratelimit-Reset	Unix epoch timestamp when your bucket is reset to full

If you receive HTTP status code 429, use the Ratelimit-Reset header to determine how long you must wait before making another request.

Twitch API Guide: EventSub

While the API provides endpoints for polling resource status, Twitch recommends subscribing to EventSub for real-time notifications. This Twitch API guide highlights EventSub as the preferred method for receiving events when changes occur, such as when a stream goes live, a user follows, or a subscription is made.

Common EventSub subscription types include:

Event Type	Description
stream.online	Broadcaster starts streaming
stream.offline	Broadcaster stops streaming
channel.follow	User follows a channel
channel.subscribe	User subscribes to a channel
channel.raid	Broadcaster raids another channel
channel.poll.begin	Poll starts on a channel
channel.prediction.begin	Prediction starts on a channel

Twitch API Guide: Python Implementation Example

Here is a complete Python example from this Twitch API guide demonstrating how to authenticate and make API requests:

import requests
import secrets
import json
from urllib.parse import urlencode

# === CONFIG ===
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
REDIRECT_URI = "http://localhost:3000"
SCOPES = "user:read:email channel:read:subscriptions"

# === Step 1: Build authorization URL ===
state = secrets.token_urlsafe(16)
auth_params = {
    "response_type": "code",
    "client_id": CLIENT_ID,
    "redirect_uri": REDIRECT_URI,
    "scope": SCOPES,
    "state": state
}
auth_url = f"https://id.twitch.tv/oauth2/authorize?{urlencode(auth_params)}"
print("Open this URL to authorize:", auth_url)

# === Step 2: After user authorizes, exchange code for tokens ===
auth_code = input("Enter the authorization code: ")

token_response = requests.post(
    "https://id.twitch.tv/oauth2/token",
    headers={"Content-Type": "application/x-www-form-urlencoded"},
    data={
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "code": auth_code,
        "grant_type": "authorization_code",
        "redirect_uri": REDIRECT_URI
    }
)

tokens = token_response.json()
access_token = tokens["access_token"]
print("Access Token obtained!")

# === Step 3: Make API request ===
user_response = requests.get(
    "https://api.twitch.tv/helix/users",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Client-Id": CLIENT_ID
    }
)

print("User Info:", json.dumps(user_response.json(), indent=2))

# === App Access Token Example ===
app_token_response = requests.post(
    "https://id.twitch.tv/oauth2/token",
    headers={"Content-Type": "application/x-www-form-urlencoded"},
    data={
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "grant_type": "client_credentials"
    }
)

app_token = app_token_response.json()["access_token"]
print("App Access Token:", app_token)

Twitch API Guide: Error Handling

The API returns standard HTTP status codes to indicate success or failure of requests. This Twitch API guide provides the following reference table:

Status Code	Meaning	Common Cause
200	OK	Request successful
204	No Content	Request successful, no response body
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Invalid or expired token, missing Client-Id header
403	Forbidden	Token lacks required scope
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side issue

Twitch API Guide: Pagination

The Twitch API supports cursor-based pagination for endpoints that return lists. Use the following query parameters to control paging as described in this Twitch API guide:

Parameter	Description
first	Number of items per page (max varies by endpoint)
after	Cursor for the next page of results
before	Cursor for the previous page of results

When more results are available, the response includes a pagination object with a cursor:

{
  "data": [...],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6Ik1qQT0ifX0"
  }
}

Use the cursor value with the after parameter to get the next page. An empty pagination object indicates no more results.

Twitch API Guide: Best Practices

This Twitch API guide recommends following these best practices for optimal integration:

• Always include Client-Id header: Every API request must include both the Authorization and Client-Id headers.
• Store secrets securely: Never expose your client_secret in client-side code. Keep all sensitive credentials server-side.
• Request minimal scopes: Only request the scopes your application actually needs. Users are more likely to approve apps with focused permissions.
• Handle token expiration: Implement automatic token refresh before expiration to maintain seamless user experience.
• Use EventSub for real-time updates: Instead of polling endpoints, subscribe to EventSub for efficient real-time notifications.
• Respect rate limits: Monitor rate limit headers and implement exponential backoff for retries.
• Validate state parameter: Always validate the state parameter in the callback to prevent CSRF attacks.
• Handle non-breaking changes: Your code should ignore unexpected fields in responses as Twitch may add new fields without notice.

Twitch API Guide: Frequently Asked Questions