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