Getting Tokens: OAuth

Introduction

There are three OAuth procedures:

The OAuth implicit code flow gets user access tokens.
The OAuth authorization code flow gets user access tokens.
The OAuth client credentials flow gets app access tokens.

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

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	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"
}