Contents

v3 to v5 Migration Guide

While you can migrate from v3 to v5, know that v5 is deprecated and will be shutdown in the future. We prefer that you migrated directly to the new Twitch API.

As previously announced, Twitch API v3 has been deprecated since the release of v5 on November 15, 2016 and we are moving forward with a controlled shutdown of v3 scheduled for September 12, 2019.

This guide will provide important information that developers should know concerning the shutdown and help migrate any current usage of v3 endpoints to v5 endpoints.

Should you have any questions or comments during this process, pleas create a topic under the /c/api/migration category on the developer forums. And as always, you can talk directly with other members of the community on the TwitchDev Discord server.

Important Dates

Default API Version

v3 is the default API version and developers will need to set an Accept header to specify that they want to reach v5 endpoints. Developers can proactively include the v5 Accept header in order to properly test their updates. Below is an example and you can visit the Requests documentation for more information.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET https://api.twitch.tv/kraken/streams/

Note that default version of the API will not be updated to v5 after the v3 shutdown and therefore the Accept header will be required for any request to the kraken namespace.

Username Versus User ID

v5 utilizes user IDs (i.e. a numerical string) to perform operations related to a Twitch user rather than usernames (i.e. a user’s login name) as is the case in v3. Some of these operations include getting a list of a user’s followers, updating a user’s profile information, and getting information about actively installed Extensions. If your application relies on usernames for API calls, please use the Get Users endpoint to translate usernames to user IDs as shown below. Up to 100 usernames can be specified at a time.

curl -H 'Client-ID: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
'https://api.twitch.tv/helix/users?login=TwitchDev&login=Twitch'

Authentication

Authentication across all versions of the Twitch API are handled with the same identity system. For any endpoint that requires or provides the option for authentication, you can obtain an app token, user access token, or an OIDC ID token. Refer to our authentication guide for more information.

Please note that the domain dedicated to Twitch authentication is https://id.twitch.tv. If your application uses https://api.twitch.tv/kraken to perform actions such as getting tokens, validating tokens, or revoking tokens, please update the URL as soon as possible. This should be a trivial replacement and will safeguard against potential issues in the future should you not make this change before v5 of the API is eventually sunset.

Scopes

When you request authorization from a user, scopes allows you to declare which permissions your application requires. These scopes are tied to the access token you receive on successful authorization. To help identify the scopes you will need in your migration process, we’ve included a comparative list below to illustrate the similarities and differences from one version of the API to the next.

v3 v5
channel_check_subscription
Read access to check if a user is subscribed to your channel.
channel_check_subscription
Read whether a user is subscribed to your channel.
channel_commercial
Access to trigger commercials on channel.
channel_commercial
Trigger commercials on channel.
channel_editor
Write access to channel metadata (game, status, etc).
channel_editor
Write channel metadata (game, status, etc).
channel_feed_edit
Ability to add posts and reactions to a channel feed
channel_feed_edit
Add posts and reactions to a channel feed.
channel_feed_read
Ability to view to a channel feed.
channel_feed_read
View a channel feed.
channel_read
Read access to non-public channel information, including email address and stream key.
channel_read
Read nonpublic channel information, including email address and stream key.
channel_stream
Ability to reset a channel’s stream key.
channel_stream
Reset a channel’s stream key.
channel_subscriptions
Read access to all subscribers to your channel.
channel_subscriptions
Read all subscribers to your channel.
chat_login
Ability to log into chat and send messages.
chat_login
(Deprecated — cannot be requested by new clients.) Log into chat and send messages.
  collections_edit
Manage a user’s collections (of videos).
  communities_edit
Manage a user’s communities.
  communities_moderate
Manage community moderators.
  openid
Use OpenID Connect authentication.
user_blocks_edit
Ability to ignore or unignore on behalf of a user.
user_blocks_edit
Turn on/off ignoring a user. Ignoring users means you cannot see them type, receive messages from them, etc.
user_blocks_read
Read access to a user’s list of ignored users.
user_blocks_read
Read a user’s list of ignored users.
user_follows_edit
Access to manage a user’s followed channels.
user_follows_edit
Manage a user’s followed channels.
user_read
Read access to non-public user information, such as email address.
user_read
Read nonpublic user information, like email address.
user_subscriptions
Read access to subscriptions of a user.
user_subscriptions
Read a user’s subscriptions.
  viewing_activity_read
Turn on Viewer Heartbeat Service ability to record user data.