Authentication

This is a guide to help developers use Twitch Authentication, which enables your application to take actions on behalf of a Twitch account or access certain data about a user’s account. There are multiple ways for you 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.

As we describe the steps, we provide sample requests that your application would make, for one of your users to grant you access to her viewing activity.

Note: For readability, some of the parameterized example code is shown on multiple lines; the real examples are on one line.

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, enter your redirect URI, which is where your 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 Access Tokens

There are two ways to get an OAuth 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) Redirect the user you want to authenticate to your registered redirect URL. Included in the request is a list of authentication scopes requested by your application.

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 auth scopes>
    &state=<your unique token generated by your application>

In our example, you request access to a user’s viewing activity (by specifying the viewing_activity_read scope) and send the user to http://localhost:

1
https://api.twitch.tv/kraken/oauth2/authorize?response_type=code&client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&redirect_uri=http://localhost&scope=viewing_activity_read&state=c3ab8aa609ea11e793ae92361f002671

An authorization page will ask the user to sign up or log in with her Twitch account and allows her 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 the redirect 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, she is redirected to your redirect URL:

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

In our example, your user gets redirected to:

1
http://localhost/?code=394a8bc98028f39660e53025de824134fb46313

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>

Here is a sample request:

1
2
3
4
POST https://api.twitch.tv/kraken/oauth2/token

POST Body (URL-encoded)
client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&client_secret=nyo51xcdrerl8z9m56w9w6wg&grant_type=authorization_code&redirect_uri=http://localhost&code=394a8bc98028f39660e53025de824134fb46313&state=c3ab8aa609ea11e793ae92361f002671

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

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

In our example:

1
2
3
4
{
   "access_token": "pk2bh6y1vi8mrn7l67bp9i6dpg2wnk",
   "scope": viewing_activity_read
}

Implicit Grant Flow

1) Send the user you want to authenticate to your registered redirect 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>

In our example, you request access to a user’s viewing activity (by specifying the viewing_activity_read scope) and send the user to http://localhost:

1
https://api.twitch.tv/kraken/oauth2/authorize?response_type=token&client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&redirect_uri=http://localhost&scope=viewing_activity_read&state=c3ab8aa609ea11e793ae92361f002671

An authorization page will ask the user to sign up or log in with herTwitch account and allows her 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 the redirect 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, she is redirected to your redirect 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>

In our example, your user gets redirected to:

1
https://localhost#access_token=pk2bh6y1vi8mrn7l67bp9i6dpg2wnk&scope=viewing_activity_read&state=c3ab8aa609ea11e793ae92361f002671

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, send the access token as a header:

curl -H "Authorization: OAuth <access token>" https://api.twitch.tv/kraken/

Revoking Access Tokens

To clean up previously obtained security credentials, use the Twitch OAuth token revocation endpoint. Its implementation follows the OAuth standard.

On your server, revoke an access token by making this request:

1
2
3
4
5
6
POST https://api.twitch.tv/kraken/oauth2/revoke

POST Body (URL-encoded)
client_id=<your client ID>
    &client_secret=<your client secret>
    &token=<your OAuth token>

For example, using our previously authenticated user, the request is:

1
2
3
4
POST https://api.twitch.tv/kraken/oauth2/revoke

POST Body (URL-encoded)
client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&client_secret=nyo51xcdrerl8z9m56w9w6wg&token=pk2bh6y1vi8mrn7l67bp9i6dpg2wnk

If successful, your request returns a 200 OK response with no body. A request with a bad token returns the same response, as there is no meaningful action a client can take after sending a bad token.

Malformed requests return 400 Bad Request, along with information about how to fix the request, typically reminding the requester to include the client_id and client_secret.

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.