Authentication

As a developer, you can request permission to take actions on behalf of a Twitch account or to access certain data about a user’s account. We provide multiple ways for developers to obtain access to a Twitch account on behalf of a user. We use parts of the OAuth 2.0 protocol.

Authentication involves:

  1. Registering your app to obtain a client ID and client secret.
  2. Getting an access token. This includes specifying scopes, or the permissions your app requires.
  3. Sending the access token in your API request, to authenticate API requests.

Registration

To make an application that uses the Twitch API, you will first need to “Register your application” from the connections tab of your Twitch settings page. When creating this app, you will need to enter your redirect URI, which is where users are redirected after being authorized.

Once you create a developer application, you are assigned a client ID. Some authentication flows also require a client secret, which you can generate on the same page as the client ID.

  • Client IDs are public and can be shared (for example, embedded in the source of a Web page).
  • Client secrets are equivalent to a password for your application and must be kept confidential. Never expose it to users, even in an obscured form.

Because your client secret is confidential, we cannot show it to you once you leave the page, so make sure to record it somewhere safe. Also, generating a new client secret immediately invalidates the current one, which might make your API requests fail until your app is updated.

Getting OAuth Access Tokens

There are two ways to get an access token:

  • Use the Authorization Code Flow if you are making a Web app that uses a server.
  • Use the Implicit Grant Flow if your app does not use a server, such as a client-side JavaScript app or mobile app. This approach does not require a server that must make requests to the API.

Authorization Code Flow

1) Send the user you want to authenticate to this URL:

1
2
3
4
5
6
https://api.twitch.tv/kraken/oauth2/authorize
     ?response_type=code
     &client_id=<your client ID>
     &redirect_uri=<your registered redirect URI>
     &scope=<space-separated list of scopes>
     &state=<your unique token generated by your application>`

This authorization page asks the user to sign up or log in with their Twitch account and allows him to choose whether to authorize your application/identity system.

We support the state OAuth2 parameter, which we strongly recommend to avoid cross-site scripting attacks. If included, it is appended to the list of query parameters when the user is redirected to the redirect_uri.

You also can append the force_verify parameter to this URL. This parameter decides whether the user should be re-prompted for authorization. The default is false: a given user sees the authorization page for a given set of scopes only the first time through the sequence. If this is set to true, the user always is prompted to confirm authorization. This is useful to allow your users to switch Twitch accounts, since there is no way to log users out of the API.

2) If the user authorizes your application, he is redirected to this URL:

1
https://<your registered redirect URI>/?code=<authorization code>

3) On your server, get an access token by making this request:

1
2
3
4
5
6
7
8
9
POST https://api.twitch.tv/kraken/oauth2/token

POST Body (URL-encoded)
client_id=<your client ID>
&client_secret=<your client secret>
&grant_type=authorization_code
&redirect_uri=<your registered redirect URI>
&code=<authorization code received above>
&state=<your unique token generated by your application>

4) We respond with a JSON-encoded access token:

1
2
3
4
{
   "access_token": "<user access token>",
   "scope":<your previously listed scopes>
}

Implicit Grant Flow

1) Send the user you want to authenticate to this URL:

1
2
3
4
5
6
https://api.twitch.tv/kraken/oauth2/authorize
       ?response_type=token
       &client_id=<your client ID>
       &redirect_uri=<your registered redirect URI>
       &scope=<space-separated list of scopes>
       &state=<your unique token generated by your application>

This authorization page asks the user to sign up or log in with their Twitch account and allows him to choose whether to authorize your application/identity system.

We support the state OAuth2 parameter, which we strongly recommend to avoid cross-site scripting attacks. If included, it is appended to the list of query parameters when the user is redirected to the redirect_uri.

You also can append the force_verify parameter to this URL. This parameter decides whether the user should be re-prompted for authorization. The default is false: a given user sees the authorization page for a given set of scopes only the first time through the sequence. If this is set to true, the user always is prompted to confirm authorization. This is useful to allow your users to switch Twitch accounts, since there is no way to log users out of the API.

2) If the user authorizes your application, he is redirected to this URL:

1
2
3
4
https://<your registered redirect URI>/
       #access_token=<an access token>
       &scope=<authorized scopes>
       &state=<your unique token generated by your application>

Here, the access token is in the URL fragment, not the query string, so it will not show up in HTTP requests to your server. URL fragments can be accessed from JavaScript with document.location.hash.

Sending Access Tokens

When an API request requires authentication, there are two ways to send the access token:

  • As a header:
    curl -H "Authorization: OAuth [access token]" https://api.twitch.tv/kraken/
  • As a URL parameter:
    curl https://api.twitch.tv/kraken?oauth_token=[access token]

Scopes

When requesting authorization from users, the URL scope parameter allows you to specify which permissions your app requires. These scopes are tied to the access token you receive on successful authorization. Without specifying scopes, your app can access only basic information about the authenticated user.

You can specify any or all of these scopes:

Scope Name Type of Access
channel_check_subscription Read whether a user is subscribed to your channel.
channel_commercial Trigger commercials on channel.
channel_editor Write channel metadata (game, status, etc).
channel_feed_edit Add posts and reactions to a channel feed.
channel_feed_read View a channel feed.
channel_read Read nonpublic channel information, including email address and stream key.
channel_stream Reset a channel’s stream key.
channel_subscriptions Read all subscribers to your channel.
chat_login 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.
user_blocks_edit Turn on/off ignoring a user. Ignoring a user means you cannot see him type, receive messages from him, etc.
user_blocks_read Read a user’s list of ignored users.
user_follows_edit Manage a user’s followed channels.
user_read Read nonpublic user information, like email address.
user_subscriptions Read a user’s subscriptions.
viewing_activity_read Turn on Viewer Heartbeat Service ability to record user data.

Scopes are specified as a space-separated list in the URL scope parameter, when requesting authorization:

&scope=user_read+channel_read

Ask for only the permissions you need, as users can view each requested permission when authorizing your app.