v5 to Twitch API Migration Guide

Overview

The following guide provides information and resources to help migrate legacy v5 integrations to the Twitch API that uses the Helix namespace. v5 was the previous version of the Twitch API and was decommissioned on February 28, 2022.

This guide may not be exhaustive, however it should cover the most common differences between the API versions to assist with updating older applications that are no longer functioning properly.

Authentication Tokens and Headers

OAuth tokens are required when requesting Twitch API endpoints. This differs from v5 where most endpoints only required the Client ID header. You will also need to use the word “Bearer” in the Authorization header instead of “OAuth.” Here is a curl example that demonstrates how to send your Client ID and OAuth token for endpoints in the Helix namespace.

curl -H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-X GET 'https://api.twitch.tv/helix/channels?broadcaster_id=12826'

Many endpoints can be requested using an app access token which will let you access non-user specific public information. Although you cannot request most scopes with this type of token, it is useful for making calls to the search endpoints, stream status endpoints, or other similar endpoints that do not require user authorization to provide privileged information (such as the subscribers endpoints which require the broadcaster to approve of third-party access). In these cases, or to scale your application for more users, consider user access tokens.

You can find some examples showing how to generate and use access tokens for the Twitch API in our Community Code resource.

Rate Limits

The Twitch API has introduced rate limits not present in v5. As such, you may need to consider some changes to your application for the information you are requesting. For example, instead of relying on an app access token that has a set rate limit, consider using a user access token in which case each user of your application is given a rate limit allowing your development to scale as your users increase. You may also need to consider timing requests to fit within the limits if an app access token must be used.

The Twitch API has a rate limit of 800 points per minute and you can use the response headers of API requests to monitor your usage to adjust as needed. For more information, please see our rate limit documentation.

Two common API use cases involve requesting streams for live streaming status and requesting users to get their username or user id. As such, we want to remind you that up to 100 streams or users can be requested in a single request, which can help an application operate within the rate limits.

Authentication Scopes

As is the case for many developers, you may already have broadcasters or users who have authorized your application to access information about their accounts. Since we want to minimize the disruption for your users, we are allowing some v5 authentication scopes to be used for requests to the latest version of the API. This means you will not have to prompt broadcasters or users to re-authenticate when switching your development from v5 endpoints to the latest endpoints.

When implementing one our our latest endpoints for the first time, for example, adding functionality that you did not provide with v5 endpoints, it is preferable to use the Twitch API scope instead of one of the v5 scopes that have been added as a migration convenience. You can find more information about scopes in our authentication documentation. As the following table indicates, each v5 scope maps to one or more Twitch API scopes; we will treat the v5 scope as an equivalent when making calls to endpoints in the Helix namespace.

Endpoint Equivalence

Each v5 endpoint that has an equivalent endpoint in our latest version of the API is listed in the following table to help update your application during the migration period.

Extension Endpoints

The endpoints defined within the original Extension reference rely on the same underlying infrastructure as v5 and are included in the decommission. Equivalent endpoints have been added to the latest API infrastructure and reference, and are detailed below. An easy way to confirm if you are using the latest endpoints is to make sure your HTTP requests include “api.twitch.tv/helix/extensions” rather than “api.twitch.tv/extensions”.