Contents

Getting OAuth Access Tokens

Twitch APIs require access tokens to access resources. Depending on the resource you’re accessing, you’ll need a user access token or app access token. The API’s reference content identifies the type of access token you’ll need. The simple difference between the two types of tokens is that a user access token lets you access a user’s sensitive data (with their permission) and an app access token lets you access their non-sensitive data only (and doesn’t require the user’s permission).

If the APIs you’re calling require an OAuth app or user access token, use one of the following flows to get the token:

Flow Token Type Description
Implicit grant flow User access token Use this flow if your app does not use a server. For example, use this flow if your app is a client-side JavaScript app or mobile app.
Authorization code grant flow User access token Use this flow if your app uses a server, can securely store a client secret, and can make server-to-server requests to the Twitch API.
Client credentials grant flow App access token Use this flow if your app uses a server, can securely store a client secret, and can make server-to-server requests to the Twitch API. This flow is meant for apps that only need an app access token.

NOTE Third-party apps that call the Twitch APIs and maintain an OAuth session must call the /validate endpoint to verify that the access token is still valid. Read more

Implicit grant flow

This flow is meant for apps that don’t use a server, such as client-side JavaScript apps or mobile apps.

To get a user access token using the implicit grant flow, navigate a user to https://id.twitch.tv/oauth2/authorize with the following query parameters that are appropriate for your application. This can be done via your application control logic or simply by adding an HTML hyperlink for a user to click if your service is a website (e.g. <a href="https://id.twitch.tv/oauth2/authorize?[parameters]">Connect with Twitch</a>).

Parameter Required? Type Description
client_id Yes String Your app’s registered client ID.
force_verify No Boolean Set to true to force the user to re-authorize your app’s access to their resources. The default is false.
redirect_uri Yes URI Your app’s registered redirect URI. The access token is sent to this URI.
response_type Yes String Must be set to token.
scope Yes String A space-delimited list of scopes. The APIs that you’re calling identify the scopes you must list. You must URL encode the list.
state No String Although optional, you are strongly encouraged to pass a state string to help prevent Cross-Site Request Forgery (CSRF) attacks. The server returns this string to you in your redirect URI (see the state parameter in the fragment portion of the URI). If this string doesn’t match the state string that you passed, ignore the response. The state string should be randomly generated and unique for each OAuth request.

The following URI is an example of the URI that you’ll navigate to in your web browser control (the URI is formatted for easier reading).

https://id.twitch.tv/oauth2/authorize
    ?response_type=token
    &client_id=hof5gwx0su6owfnys0yan9c87zr6t
    &redirect_uri=http://localhost:3000
    &scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls
    &state=c3ab8aa609ea11e793ae92361f002671

If the user is logged into Twitch, Twitch asks them to authorize your application’s access to the specified resources. If they’re not logged in, Twitch first asks them to log in and then asks them to authorize your application.

If the user authorizes your application by clicking Authorize, the server sends the access token to your redirect URI in the fragment portion of the URI (see the access_token parameter):

http://localhost:3000/
    #access_token=73d0f8mkabpbmjp921asv2jaidwxn
    &scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls
    &state=c3ab8aa609ea11e793ae92361f002671
    &token_type=bearer

NOTE In JavaScript, you can access the fragment using document.location.hash.

If the user didn’t authorize your app, the server sends the error code and description to your redirect URI (see the error and error_description query parameters).

http://localhost:3000/
    ?error=access_denied
    &error_description=The+user+denied+you+access
    &state=c3ab8aa609ea11e793ae92361f002671

Authorization code grant flow

This flow is meant for apps that use a server, can securely store a client secret, and can make server-to-server requests to the Twitch API. To get a user access token using the authorization code grant flow, your app performs the following steps:

Get the user to authorize your app

The first step is to get the user to authorize your application’s access to their resources. To get the authorization, in your web browser control, have your users navigate to https://id.twitch.tv/oauth2/authorize with the following query parameters that are appropriate for your application. This can be done with an HTML hyperlink (i.e. <a href="https://id.twitch.tv/oauth2/authorize?[parameters]">Connect with Twitch</a>). You can also navigate to the URL yourself in a web browser once the parameters have been added to test the authorization flow.

Parameter Required? Type Description
client_id Yes String Your app’s registered client ID.
force_verify No Boolean Set to true to force the user to re-authorize your app’s access to their resources. The default is false.
redirect_uri Yes URI Your app’s registered redirect URI. The authorization code is sent to this URI.
response_type Yes String Must be set to code.
scope Yes String A space-delimited list of scopes. The APIs that you’re calling will identify the scopes you must list. You must URL encode the list.
state No String Although optional, you are strongly encouraged to pass a state string to help prevent Cross-Site Request Forgery (CSRF) attacks. The server returns this string to you in your redirect URI (see the state parameter in the fragment portion of the URI). If this string doesn’t match the state string that you passed, ignore the response. The state string should be randomly generated and unique for each OAuth request.

The following URI shows an example request that you’ll navigate to in your web browser control (the URI is formatted for easier reading).

https://id.twitch.tv/oauth2/authorize
    ?response_type=code
    &client_id=hof5gwx0su6owfnys0nyan9c87zr6t
    &redirect_uri=http://localhost:3000
    &scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls
    &state=c3ab8aa609ea11e793ae92361f002671

If the user is logged into Twitch, Twitch asks them to authorize your application’s access to the specified resources. If they’re not logged in, Twitch first asks them to log in and then asks them to authorize your application.

If the user authorized your app by clicking Authorize, the server sends the authorization code to your redirect URI (see the code query parameter):

http://localhost:3000/
    ?code=gulfwdmys5lsm6qyz4xiz9q32l10
    &scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls
    &state=c3ab8aa609ea11e793ae92361f002671

If the user didn’t authorize your app, the server sends the error code and description to your redirect URI (see the error and error_description query parameters):

http://localhost:3000/
    ?error=access_denied
    &error_description=The+user+denied+you+access
    &state=c3ab8aa609ea11e793ae92361f002671

Use the authorization code to get a token

The second step in this flow is to use the authorization code (see above) to get an access token and refresh token.

To get the tokens, send an HTTP POST request to https://id.twitch.tv/oauth2/token. Set the following x-www-form-urlencoded parameters in the body of the POST.

Parameter Required? Type Description
client_id Yes String Your app’s registered client ID.
client_secret Yes String Your app’s registered client secret.
code Yes String The code that the /authorize response returned in the code query parameter.
grant_type Yes String Must be set to authorization_code.
redirect_uri Yes URI Your app’s registered redirect URI.

The following example shows the parameters in the body of the POST (the parameters are formatted for easier reading).

client_id=hof5gwx0su6owfnys0yan9c87zr6t
&client_secret=41vpdji4e9gif29md0ouet6fktd2
&code=gulfwdmys5lsm6qyz4xiz9q32l10
&grant_type=authorization_code
&redirect_uri=http://localhost:3000

If the request succeeds, it returns an access token and refresh token.

{
  "access_token": "rfx2uswqe8l4g1mkagrvg5tv0ks3",
  "expires_in": 14124,
  "refresh_token": "5b93chm6hdve3mycz05zfzatkfdenfspp1h1ar2xxdalen01",
  "scope": [
    "channel:moderate",
    "chat:edit",
    "chat:read"
  ],
  "token_type": "bearer"
}

When the access token expires, use the refresh token to get a new access token. For information about using refresh tokens, see Refreshing Access Tokens.

Client credentials grant flow

The client credentials grant flow is meant only for server-to-server API requests that use an app access token.

To get an access token, send an HTTP POST request to https://id.twitch.tv/oauth2/token. Set the following x-www-form-urlencoded parameters as appropriate for your app.

Parameter Required? Type Description
client_id Yes String Your app’s registered client ID.
client_secret Yes String Your app’s registered client secret.
grant_type Yes String Must be set to client_credentials.

The following example shows the parameters in the body of the POST (the parameters are formatted for easier reading).

client_id=hof5gwx0su6owfnys0yan9c87zr6t
&client_secret=41vpdji4e9gif29md0ouet6fktd2
&grant_type=client_credentials

If the request succeeds, it returns an access token.

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

Examples of the three flows

If you don’t want to write code to test the OAuth flows in this topic, try the following options. Before continuing, you’ll need to register an app to get a client ID and secret that you can use below. When registering your app, use http://localhost:3000 for your redirect URI.

Implicit flow example

Open your favorite browser and enter the following URI in the address bar. Substitute your client ID for the placeholder string.

https://id.twitch.tv/oauth2/authorize?response_type=token&client_id=<your client id goes here>&redirect_uri=http://localhost:3000&scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls&state=c3ab8aa609ea11e793ae92361f002671

If you’re not already signed in to your Twitch account, you’ll be asked to sign in. If this client ID hasn’t previously requested access to your Poll resource, you’ll be asked to give consent. If you want to always force consent, include the force_verify query parameter.

If you consented, the address bar is set to your redirect URI and it contains the access token (see access_token in the URI’s fragment).

http://localhost:3000/#access_token=wt6oxekssgvj53dkf38grzyzh2xe&scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls&state=c3ab8aa609ea11e793ae92361f002671&token_type=bearer

Authorization code flow example

Open your favorite browser and enter the following URI in the address bar. Substitute your client ID for the placeholder string.

https://id.twitch.tv/oauth2/authorize?response_type=code&client_id=<your client id goes here>&redirect_uri=http://localhost:3000&scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls&state=c3ab8aa609ea11e793ae92361f002671

If you’re not already signed in to your Twitch account, you’ll be asked to sign in. If this client ID hasn’t previously requested access to your Poll resource, you’ll be asked to give consent. If you want to always force consent, include the force_verify query parameter.

If you consented, the address bar is set to your redirect URI and it contains the authorization code (see the code parameter).

http://localhost:3000/?code=17038swieks1jh1hwcdr36hekyui&scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls&state=c3ab8aa609ea11e793ae92361f002671

Open a terminal window and enter the following cURL POST command (you’ll need cURL installed on your computer). Replace the placeholder strings and the authorization code with your values.

curl -X POST 'https://id.twitch.tv/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=<your client id goes here>&client_secret=<your client secret goes here>&code=17038swieks1jh1hwcdr36hekyui&grant_type=authorization_code&redirect_uri=http://localhost:3000'

The response contains a JSON object with the access token and refresh token.

{
  "access_token": "fvc8xeeajsh0zkunt6fby67rnyux1",
  "expires_in": 15485,
  "refresh_token": "e2zyj5itwcmlg2clbcnd1wqlibypzjjydwu26bfhqhx1klp2o",
  "scope": [
    "channel:manage:polls",
    "channel:read:polls"
  ],
  "token_type": "bearer"
}

Client credentials flow example

Open a terminal window and enter the following cURL POST command (you’ll need cURL installed on your computer).

curl -X POST 'https://id.twitch.tv/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=<your client id goes here>&client_secret=<your client secret goes here>&grant_type=client_credentials'

The response contains a JSON object with the access token.

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