Authentication Guide

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.

In addition to OAuth, Twitch supports OIDC (OpenID Connect) for a more secure OAuth 2.0 flow. OIDC tokens are compatible with services built for OIDC compliance, such as Cognito by Amazon Web Services.

Authentication involves:

  1. Registering your app to obtain a client ID and client secret.
  2. Getting a token. This includes specifying scopes, or the permissions your app requires.
  3. Sending the 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.

If You Use Twitch for Login to Your App, You Must Validate Every Request

This section applies only to developers who use Twitch to enable users to log into their applications. In these cases, Twitch ensures that users who identify themselves on third-party Web sites are who they say they are.

Twitch requires that applications using Twitch OAuth 2 authentication for login validate the access tokens with every request. That is, if your service uses Twitch as a form of authentication (to verify that a user is who he says he is on your platform), each request to your service must validate the continued viability of the access token.

Twitch periodically conducts audits. If we discover an application that is not re-validating access tokens (that is, an application that validates only for login and not thereafter), we may take punitive action, such as revoking the developer’s API key or throttling the application’s performance.

This is important because of how OAuth 2 tokens work and the end user's expectation of OAuth 2 session control. For example, if a user opts to disconnect your integration from her Twitch account, she can do so from her account settings on Twitch. When a user disconnects from an integration, all OAuth 2 tokens between that user and that integration are invalidated. In this scenario, the expectation is that OAuth 2 tokens are tied to sessions on third-party party services; as such, any existing sessions between the disconnected user and those services also should be invalidated.

When validating each of your requests, submit a request to the root URL. If you are authenticated, the response includes the status of your token. The response includes a token object, and if the valid field in that object is true, your access token is valid.

Registration

To make an application that uses the Twitch API, you first need to register your application on the Twitch developer site. 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.

Types of Tokens

Twitch supports several types of tokens:

Token Type Description
ID tokens (OIDC) A set of claims about the end user, for a given authorization. Using OIDC ID tokens (JWT) enables you to get details about your user (such as email address) for a particular authorization. These details are represented by claims in the ID token’s payload.

Our discovery endpoint is at https://api.twitch.tv/api/.well-known/openid-configuration. It can be used with standard OIDC clients like AWS Cognito.
User access tokens Authenticate users and allow your app to make requests on their behalf. If your application uses Twitch for login or makes requests in the context of an authenticated user, you need to generate a user access token.
App access tokens Authenticate your app and allow it to access resources that it owns. Since app access tokens are not associated with a user, they cannot be used with endpoints that require user authentication.

Some Twitch API endpoints require application authentication (not user authentication). If your application uses these endpoints, you need to generate an app access token. App access tokens get client credentials (not user credentials). They enable you to make secure API requests that are not on behalf of a specific user. Client credentials also may be used in place of client ID headers to securely identify your application.

App access tokens expire after about 60 days, so you should check that your app access token is valid by submitting a request to the root URL. If your token has expired, generate a new one.

App access tokens are meant only for server-to-server API requests and should never be included in client code.

Getting Tokens

We support several authentication flows:

Flow Type Description
Implicit code flow 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 Your application uses a server, can securely store a client secret, and can make server-to-server requests.
Client credentials flow You need an app access token.

The procedure you should use to get tokens depends on the type(s) of tokens you want:

Procedure User Access Token ID Token App Access Token
OIDC Implicit Code Flow
OAuth Implicit Code Flow
OIDC Authorization Code Flow
OAuth Authorization Code Flow
OAuth Client Credentials Flow

Note: For security purposes, examples in these sections use a fake access token, 0123456789abcdefghijABCDEFGHIJ.

OIDC Implicit Code Flow (ID Tokens and Optional User Access Tokens)

1) Send the user you want to authenticate to your registered redirect URI. Then, an authorization page will ask the user to sign up or log in with her Twitch account and allow the user to choose whether to authorize your application/identity system.

Use this request:

GET https://api.twitch.tv/kraken/oauth2/authorize
    ?client_id=<your client ID>
    &redirect_uri=<your registered redirect URI>
    &response_type=<type>
    &scope=<space-separated list of scopes>

There are several required and optional query-string parameters:

Required Parameter Type Description
client_id string Your client ID.
redirect_uri URI Your registered redirect URI. This must exactly match the redirect URI registered in the prior, Registration step.
response_type string There are two valid values:

* token id_token – Return an access token and an ID token (JWT). A given user is prompted to confirm authorization only on the first request. This should be URL encoded as token+id_token or token%20id_token.
* id_token – Return only an ID token. For example, a client with a valid access token, who only needs added information about the user authorizing it, might specify this option.
scope string Space-separated list of scopes. This must include the openid scope.
Optional Parameter Type Description
nonce string OIDC opaque value to avoid CSRF attacks. (Specifically, this is used to associate the client's authorization session with an ID token, to avoid replay attacks.) This value is echoed back in the response. We strongly recommend you use this.
state string Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.

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:

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-X GET 'https://api.twitch.tv/kraken/oauth2/authorize?response_type=token+id_token&client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&redirect_uri=http://localhost&scope=viewing_activity_read&state=c3ab8aa609ea11e793ae92361f002671'

2) If the user authorizes your application, she is sent to your redirect URI, with an ID token and optionally an access token (if that was requested):

https://<your registered redirect URI>#id_token=<an id token>&access_token=<an access token>

Several claims about the OIDC ID token are included in the payload of the JWT that is returned:

  • iss – Token issuer (Twitch)
  • sub – Subject or end-user identifier
  • aud – Audience or OAuth 2.0 client that is the intended recipient of the token
  • exp – Expiration time (note that when the JWT ID tokens expire, they cannot be refreshed)
  • iat – Issuance time
  • nonce – Value optionally specified in the request

The ID and access tokens are in the URL fragment, not the query string, so they will not show up in HTTP requests to your server. URI fragments can be accessed from JavaScript with document.location.hash.

The response includes the state parameter in the URL fragment and/or the nonce parameter in the ID token’s payload, if they were provided on your initial request.

Here is a sample response with both an ID token and access token:

https://localhost#access_token=0123456789abcdefghijABCDEFGHIJ
&token_type=bearer
&id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjRvaXU4In0.eyJzdWIiOiJuZnlmZSIsImF1ZCI6ImltX29pY19jbGllbnQiLCJqdGkiOiJUOU4xUklkRkVzUE45enU3ZWw2eng2IiwiaXNzIjoiaHR0cHM6XC9cL3Nzby5tZXljbG91ZC5uZXQ6OTAzMSIsImlhdCI6MTM5MzczNzA3MSwiZXhwIjoxMzkzNzM3MzcxLCJub25jZSI6ImNiYTU2NjY2LTRiMTItNDU2YS04NDA3LTNkMzAyM2ZhMTAwMiIsImF0X2hhc2giOiJrdHFvZVBhc2praVY5b2Z0X3o5NnJBIn0.g1Jc9DohWFfFG3ppWfvW16ib6YBaONC5VMs8J61i5j5QLieY-mBEeVi1D3vr5IFWCfivY4hZcHtoJHgZk1qCumkAMDymsLGX-IGA7yFU8LOjUdR4IlCPlZxZ_vhqr_0gQ9pCFKDkiOv1LVv5x3YgAdhHhpZhxK6rWxojg2RddzvZ9Xi5u2V1UZ0jukwyG2d4PRzDn7WoRNDGwYOEt4qY7lv_NO2TY2eAklP-xYBWu0b9FBElapnstqbZgAXdndNs-Wqp4gyQG5D0owLzxPErR9MnpQfgNcai-PlWI_UrvoopKNbX0ai2zfkuQ-qh6Xn8zgkiaYDHzq4gzwRfwazaqA
&state=c3ab8aa609ea11e793ae92361f002671
	&scope=viewing_activity_read

3) Validate the ID token. This is an important security measure to ensure the authenticity of the token and guard against any tampering.

To verify the signature of our ID tokens, we host a public JSON Web Key (JWK) here. For details on how to use our JWK in validating ID tokens, see How to validate an OpenID Connect ID token.

OIDC Authorization Code Flow (ID Tokens and User Access Tokens)

1) Send the user you want to authenticate to your registered redirect URI. Then, an authorization page will ask the user to sign up or log in with her Twitch account and allow the user to choose whether to authorize your application/identity system. Use this request:

GET https://api.twitch.tv/kraken/oauth2/authorize
    ?client_id=<your client ID>
    &redirect_uri=<your registered redirect URI>
    &response_type=code
    &scope=<space-separated list of scopes>

There are several required and optional query-string parameters:

Required Parameter Type Description
client_id string Your client ID.
redirect_uri URI Your registered redirect URI. This must exactly match the redirect URI registered in the prior, Registration step.
response_type string This must be code, causing an authorization code to be returned, which is used later in this procedure. A given user is prompted to confirm authorization only on the first request.
scope string Space-separated list of scopes. This must include the openid scope.
Optional Parameter Type Description
nonce string OIDC opaque value to avoid CSRF attacks. (Specifically, this is used to associate the client's authorization session with an ID token, to avoid replay attacks.) This value is echoed back within the ID token. We strongly recommend you use this.
state string Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.

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:

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-X GET 'https://api.twitch.tv/kraken/oauth2/authorize?response_type=code&client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&redirect_uri=http://localhost&scope=viewing_activity_read&state=c3ab8aa609ea11e793ae92361f002671'

2) If the user authorizes your application, she is redirected to your redirect URI, with an authorization code:

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

The OAuth 2.0 authorization code is a 30-character, randomly generated string. It is used in the next step, a request made to the token endpoint in exchange for access and ID tokens.

The response includes the state parameter in the query string and/or the nonce parameter in the ID token’s payload, if they were provided on your initial request.

In our example, your user gets redirected to:

http://localhost/?code=394a8bc98028f39660e53025de824134fb46313
	&scope=viewing_activity_read
	&state=c3ab8aa609ea11e793ae92361f002671

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

POST https://api.twitch.tv/api/oauth2/token
    ?client_id=<your client ID>
    &client_secret=<your client secret>
    &code=<authorization code received above>
    &grant_type=authorization_code
    &redirect_uri=<your registered redirect URI>

Here is a sample request:

POST https://api.twitch.tv/api/oauth2/token
?client_id=uo6dggojyb8d6soh92zknwmi5ej1q2
&client_secret=nyo51xcdrerl8z9m56w9w6wg
&grant_type=authorization_code
&redirect_uri=http://localhost
&code=394a8bc98028f39660e53025de824134fb46313

4) We respond with a JSON-encoded access token and an ID token. Several claims about the OIDC ID token are included in the payload of the JWT that is returned:

  • iss – Token issuer (Twitch)
  • sub – Subject or end-user identifier
  • aud – Audience or OAuth 2.0 client that is the intended recipient of the token
  • exp – Expiration time (note that when the JWT ID tokens expire, they cannot be refreshed)
  • iat – Issuance time
  • nonce – Value optionally specified in the request

Here is a sample response:

{
   "access_token": "0123456789abcdefghijABCDEFGHIJ",
   "refresh_token": "eyJfaWQmNzMtNGCJ9%6VFV5LNrZFUj8oU231/3Aj",
   "expires_in": 3600,
   "scope": "viewing_activity_read",
   "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxNDk0MzkxNDQiLCJ1cGRhdGVkX2F0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoiLCJpc3MiOiJodHRwczovL3Bhc3Nwb3J0LnR3aXRjaC50diIsImF1ZCI6IjJrOGl6MnE0eG1scDM2MmQyaWR5YzBoNnA0MmQxZSIsImV4cCI6IjIwMTctMDUtMDVUMjI6MzI6MjcuNzk1MzQxNjI1WiIsImlhdCI6MTQ5NDAyMjY0N30=.6HkHCuwUufojZn3ogeyl8Bi0J8IyVjIzrTLLR-v-MpmP2-EYExjVT_aPjoIfuOmfK2cCDCsGSRL-p7rtFamuv3e4v--S_TkhekLioAdL-9Nm-ZnX8kdys9XYLEf8acFkQOmQ2W5DLfm68u3zAmpRMXsq_LPcsWVbPe5AGZK4Tt5mS5JIK1S8VCPTQLc7__rMI_3Hzpij09fILlbaicAKPqybLnqfMowyemcWmrecseNc_Jig_ZpGm7RqNkbxctBIBDouB_rGtH1R1CwlDs_PE5pSq4I67G6aoL0P4aUIOpFCXxLU45975ZdQDRRq3o2Lqce6cmRLOemO5JSCyTGZhQ=="
}

5) Validate the ID token. This is an important security measure to ensure the authenticity of the token and guard against any tampering.

To verify the signature of our ID tokens, we host a public JSON Web Key (JWK) here. For details on how to use our JWK in validating ID tokens, see How to validate an OpenID Connect ID token.

OAuth Implicit Code Flow (User Access Tokens)

1) Send the user you want to authenticate to your registered redirect URI. Then, an authorization page will ask the user to sign up or log in with her Twitch account and allow the user to choose whether to authorize your application/identity system.

Use this request:

GET https://api.twitch.tv/kraken/oauth2/authorize
    ?client_id=<your client ID>
    &redirect_uri=<your registered redirect URI>
    &response_type=<type>
    &scope=<space-separated list of scopes>

There are several required and optional query-string parameters:

Required Parameter Type Description
client_id string Your client ID.
redirect_uri URI Your registered redirect URI. This must exactly match the redirect URI registered in the prior, Registration step.
response_type string Specifies what information to return. This must be token, to return an access token. The user may be prompted to confirm authorization once or repeatedly; this is controlled by the optional force_verify parameter, below.
scope string Space-separated list of scopes.
Optional Parameter Type Description
force_verify boolean Specifies whether the user should be re-prompted for authorization. If this is 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. Default: false (a given user sees the authorization page for a given set of scopes only the first time through the sequence).
state string Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.

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:

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/oauth2/authorize?response_type=token&client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&redirect_uri=http://localhost&scope=viewing_activity_read&state=c3ab8aa609ea11e793ae92361f002671'

2) If the user authorizes your application, she is redirected to your redirect URL:

https://<your registered redirect URI>#access_token=<an access token>

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

The response includes the nonce and state parameters, if they were in your request.

In our example, your user gets redirected to:

https://localhost#access_token=0123456789abcdefghijABCDEFGHIJ
	&scope=viewing_activity_read
	&state=c3ab8aa609ea11e793ae92361f002671

OAuth Authorization Code Flow (User Access Tokens)

1) Send the user you want to authenticate to your registered redirect URI. Then, an authorization page will ask the user to sign up or log in with her Twitch account and allow the user to choose whether to authorize your application/identity system. Use this request:

GET https://api.twitch.tv/kraken/oauth2/authorize
    ?client_id=<your client ID>
    &redirect_uri=<your registered redirect URI>
    &response_type=code
    &scope=<space-separated list of scopes>

There are several required and optional query-string parameters:

Required Parameter Type Description
client_id string Your client ID.
redirect_uri URI Your registered redirect URI. This must exactly match the redirect URI registered in the prior, Registration step.
response_type string This must be code, causing an authorization code to be returned, which is used later in this procedure. A given user is prompted to confirm authorization only on the first request.
scope string Space-separated list of scopes.
Optional Parameter Type Description
force_verify boolean Specifies whether the user should be re-prompted for authorization. If this is 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. Default: false (a given user sees the authorization page for a given set of scopes only the first time through the sequence).
state string Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.

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:

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/oauth2/authorize?response_type=code&client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&redirect_uri=http://localhost&scope=viewing_activity_read&state=c3ab8aa609ea11e793ae92361f002671'

2) If the user authorizes your application, she is redirected to your redirect URI, with an authorization code:

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

The OAuth 2.0 authorization code is a 30-character, randomly generated string. It is used in the next step, a request made to the token endpoint in exchange for an access token.

The response includes the state parameter, if it was in your request.

In our example, your user gets redirected to:

http://localhost/?code=394a8bc98028f39660e53025de824134fb46313
	&scope=viewing_activity_read
	&state=c3ab8aa609ea11e793ae92361f002671

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

POST https://api.twitch.tv/kraken/oauth2/token
    ?client_id=<your client ID>
    &client_secret=<your client secret>
    &code=<authorization code received above>
    &grant_type=authorization_code
    &redirect_uri=<your registered redirect URI>

Here is a sample request:

POST https://api.twitch.tv/kraken/oauth2/token
    ?client_id=uo6dggojyb8d6soh92zknwmi5ej1q2
    &client_secret=nyo51xcdrerl8z9m56w9w6wg
    &code=394a8bc98028f39660e53025de824134fb46313
    &grant_type=authorization_code
    &redirect_uri=http://localhost

4) We respond with a JSON-encoded access token. The response looks like this:

{
   "access_token": "<user access token>",
   "refresh_token": "<refresh token>",
   "expires_in": <number of seconds until the token expires>,
   "scope": <your previously listed scope(s)>
}

In our example:

{
   "access_token": "0123456789abcdefghijABCDEFGHIJ",
   "refresh_token": "eyJfaWQmNzMtNGCJ9%6VFV5LNrZFUj8oU231/3Aj",
   "expires_in": 3600,
   "scope": viewing_activity_read
}

OAuth Client Credentials Flow (App Access Tokens)

As mentioned earlier, app access tokens are only for server-to-server API requests. The grant request below requires the client secret to acquire an app access token; this also should be done only as a server-to-server request, never in client code.

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

POST https://api.twitch.tv/kraken/oauth2/token
    ?client_id=<your client ID>
    &client_secret=<your client secret>
    &grant_type=client_credentials
    &scope=<space-separated list of scopes>

Here is a sample request:

POST https://api.twitch.tv/kraken/oauth2/token?client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&client_secret=nyo51xcdrerl8z9m56w9w6wg&grant_type=client_credentials

There are several required and optional query-string parameters:

Required Parameter Type Description
client_id string Your client ID.
client_secret string Your client secret.
grant_type string This must be client credentials.
Optional Parameter Type Description
scope string Space-separated list of scopes.

2) We respond with a JSON-encoded app access token. The response looks like this:

{
   "access_token": "<user access token>",
   "refresh_token": ""
   "expires_in": <number of seconds until the token expires>,
   "scope": "<your previously listed scope(s)>"
}

In our example:

{
   "access_token": "prau3ol6mg5glgek8m89ec2s9q5i3i",
   "refresh_token": ""
   "expires_in": 3600,
   "scope": []
}

Sending User Access and App Access Tokens

When an API request requires authentication, send the access token as a header. The header differs, depending on which API you use:

In the new Twitch API:
curl -H "Authorization: Bearer <access token>" https://api.twitch.tv/helix/

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

Revoking Access Tokens

To clean up previously obtained access tokens, use the Twitch OAuth token-revocation endpoint. Its implementation follows the OAuth standard.

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

POST https://api.twitch.tv/kraken/oauth2/revoke
    ?client_id=<your client ID>
    &token=<your OAuth token>

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

POST https://api.twitch.tv/kraken/oauth2/revoke?client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&token=0123456789abcdefghijABCDEFGHIJ

This request also works for app access tokens. To revoke the app access token we created previously, make this request:

POST https://api.twitch.tv/kraken/oauth2/revoke?client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&token=prau3ol6mg5glgek8m89ec2s9q5i3i

Both successful requests and requests with bad tokens return 200 OK with no body. Requests with bad tokens return 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.

Refreshing Access Tokens

New OAuth2 access tokens have expirations. Token-expiration periods vary in length, based on how the token was acquired. Tokens return an expires_in field indicating how long the token should last. However, you should build your applications in such a way that they are resilient to token authentication failures. In other words, an application capable of refreshing tokens should not need to know how long a token will live. Rather, it should be prepared to deal with the token becoming invalid at any time.

To allow for applications to remain authenticated for long periods in a world of expiring tokens, we allow for sessions to be refreshed, in accordance with the guidelines in "Refreshing an Access Token” in the OAuth2 RFC. Generally, refresh tokens are used to extend the lifetime of a given authorization.

Token expirations do not affect existing tokens. In the future, we will revoke permanently-lived sessions.

(Note that app access tokens and ID tokens cannot be refreshed.)

How to Refresh

To refresh a token, you need an access token/refresh token pair coming from a body. For example:

{
   "access_token": "0123456789abcdefghijABCDEFGHIJ",
   "refresh_token": "eyJfaWQmNzMtNGCJ9%6VFV5LNrZFUj8oU231/3Aj",
   "expires_in": 3600,
   "scope": "viewing_activity_read"
}

You also need the client_id and client_secret used to generate the above access token/refresh token pair

To refresh, use this request:

curl -X POST https://api.twitch.tv/kraken/oauth2/token 
    --data-urlencode
    ?grant_type=refresh_token
    &refresh_token=<your refresh token>
    &client_id=<your client ID>
    &client_secret=<your client secret>

There are several required parameters and one optional parameter:

Required Parameters Type Description
client_id string Your client ID.
client_secret string Your client secret.
grant_type string Must be refresh_token.
refresh_token string Refresh token issued to the client.

Your refresh token may contain characters that are not URL safe, so be sure to URL encode the characters of your refresh token before inserting it into the body of the refresh request. Otherwise, you may get an error (“Invalid refresh token”) when you try to refresh.
Optional Parameter Type Description
scope string Space-separated list of scopes. This must be the entire set or any subset of the scopes assigned to the original token grant. It cannot include any scope not originally granted by the resource owner. Default: the entire set of scopes originally granted.

Example:

curl -X POST https://api.twitch.tv/kraken/oauth2/token
    --data-urlencode
    ?grant_type=refresh_token
    &refresh_token=eyJfaWQmNzMtNGCJ9%6VFV5LNrZFUj8oU231/3Aj
    &client_id=fooid
    &client_secret=barbazsecret

Here is a sample response on success. It contains the new access token, refresh token, and scopes associated with the new grant. Your application should then update its record of the refresh token to be the value provided in this response, as the refresh token may change between requests.

{
    "access_token": "asdfasdf",
    "refresh_token": "eyJfMzUtNDU0OC04MWYwLTQ5MDY5ODY4NGNlMSJ9%asdfasdf=",
    "scope": "viewing_activity_read"
}

Here is the body of an unsuccessful response:

{
    "error": "Bad Request",
    "status": 400,
    "message": "Invalid refresh token"
}

Refresh in Response to Server Rejection for Bad Authentication

We recommend that you refresh your tokens in response to being rejected by the server for bad authentication. It is good practice to assume that your access token can expire or be revoked at any time, and refreshing reactively ensures that your application is prepared to deal with such situations as gracefully as possible. For this reason, refreshing in response to server rejection is preferable to refreshing proactively, on a fixed schedule.

When you make a request with expired or incorrect authorization credentials, the API returns a WWW-Authenticate header (with an invalid_token error) and a 401 Unauthorized status:

DELETE /kraken/users/test_user1/follows/channels/test_channel HTTP/1.1
Host: api.twitch.tv
User-Agent: curl/7.43.0
Accept: application/vnd.twitchtv.v3+json
Authorization: OAuth <access_token>
Client-ID: retgzhvpsxjwun0rvrb1rfwheegu1yw

HTTP/1.1 401 Unauthorized
Accept-Ranges: bytes
Access-Control-Allow-Headers:
Access-Control-Allow-Methods:
Access-Control-Allow-Origin: *
Age: 0
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json; charset=utf-8
Date: Wed, 12 Oct 2016 22:25:10 GMT
Server: nginx
Status: 401 Unauthorized
Vary: Accept-Encoding
Via: 1.1 varnish
WWW-Authenticate: OAuth realm='TwitchTV', error='invalid_token'
Content-Length: 89
Connection: keep-alive

{
    "error": "Unauthorized",
    "message": "Token invalid or missing required scope",
    "status": 401
}

On seeing a 401 error with a WWW-Authenticate header, an application should try to refresh the session if a refresh token is present. If the refresh fails, the application should re-prompt the end user with another authentication dialog via the standard OAuth 2 flow.

Handling Token Refreshes in an Application

We recommend that you do access-token refreshes synchronously with respect to all consumers of a given access token. That is, do not send multiple, simultaneous refresh requests for the same token. Send one refresh request, then redistribute the new token that is returned from that request to all consumers, as appropriate.

The API limits the number of active access tokens associated with a given refresh token. As a result, if multiple threads sharing the same authorization were to simultaneously refresh, some of them might not have working credentials at the end of the refresh. Synchronizing on the refresh operation prevents the application from inadvertently overrunning its limit.

Scopes

As mentioned above, when you request 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.

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

&scope=user:edit+user:read:email

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

New Twitch API

You can specify any or all of these scopes:

Scope Name Type of Access
user:edit Manage a user object.
user:read:email Read authorized user's email address.

Twitch API v5

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.
openid Use OpenID Connect authentication.
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.