Contents

Getting Tokens: OAuth

Introduction

There are three OAuth procedures:

See the Apps & Authentication Guide for an explanation of the different types of procedures.

OAuth Implicit Code Flow

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 into Twitch and allow the user to choose whether to authorize your application/identity system.

Use this request:

GET https://id.twitch.tv/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:

GET 'https://id.twitch.tv/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, the user 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 state parameter, if it was in your request.

In our example, your user gets redirected to:

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

OAuth Authorization Code Flow

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 into Twitch and allow the user to choose whether to authorize your application/identity system. Use this request:

GET https://id.twitch.tv/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:

GET 'https://id.twitch.tv/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, the user 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://id.twitch.tv/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://id.twitch.tv/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)>"],
  "token_type": "bearer"
}

In our example:

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

OAuth Client Credentials Flow

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://id.twitch.tv/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://id.twitch.tv/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)>"],
  "token_type": "bearer"
}

In our example:

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