Skip to content

Latest commit

 

History

History
209 lines (135 loc) · 11.3 KB

token.md

File metadata and controls

209 lines (135 loc) · 11.3 KB
Raw

Token

Overview

The token product is used to fetch access tokens for an application

Token Types

The Twitch CLI provides access to two types of tokens: App Access Tokens and User Access Tokens.

App Access Tokens

App Access Tokens can access APIs that don't require the user's permission. For example, getting a list of videos.

User Access Tokens

User Access Tokens provide access to APIs a user must grant permission to. For example, starting or stopping a poll. The specific APIs and functionality granted to a token is defined via scopes.

Client IDs and Client Secrets

Getting Access Tokens requires use of a Client ID and Client Secret which are associated with a Twitch Developer's Application. Creating an application is done by registration. Details on that process are here. Client IDs are generated automatically when an application is registered. Client Secrets must be generated explicitly. This can be done by visiting the Developer Applications Console, choosing "Manage" for the app, then using the "New Secret" button at the bottom of the page.

Adding the Client ID and Client Secret to the CLI tool is done with:

twitch configure

Running that starts prompts asking for the credentials.

Fetching App Access Tokens

App Access Tokens can be fetched once the Client ID and Client Secret have been entered. No other configuration is necessary. The command is:

twitch token

Running that returns a result with the token like:

2023/08/23 13:19:08 App Access Token: 01234abcdetc...

Fetching User Access Tokens

Fetching User Access Tokens requires setting an OAuth Redirect URL. Those URLs are defined on the Manage page for each app in the Developer's Application Console. The twitch CLI uses http://localhost:3000. Two important notes when adding that to the OAuth Redirect URLs section:

  1. Do not add a / to the end of the URL (i.e. use http://localhost:3000 and not http://localhost:3000/)
  2. The OAuth Redirect URLs section allows up to ten URLs. The http://localhost:3000 must be the first one

The User Flag

The -u flag is what sets the token product to fetch a User Access Token instead of an App Access Token.

Scopes

User Access Tokens use scopes to determine which APIs and features they have access to. The requested scopes are defined via a space separated list following an -s flag with the token product.

The full list of available scopes here in the Twitch Documentation

Example

A full example fetching a User Access Token with the ability to do shoutouts and set shield modes looks like this:

twitch token -u -s "moderator:manage:shoutouts moderator:manage:shield_mode"

Running that produce some initial output in the terminal and opens a browser to a Twitch authorization page. If you're not already signed in, you'll be asked to do so. When signed-in, the page displays the authorization request including the requested scopes. Clicking the "Authorize" button at the bottom redirects the browser back to the http://localhost:3000 address where the twitch CLI picks it up and complete the process by parsing the data returned in the URL.

The browser will display a message like:

Feel free to close this browser window.

The terminal outputs the tokens in a response like this:

Opening browser. Press Ctrl+C to cancel...
2023/08/23 13:50:00 Waiting for authorization response ...
2023/08/23 13:50:03 Closing local server ...
2023/08/23 13:50:10 User Access Token: 012345asdfetc...
Refresh Token: 012345asdfetc...
Expires At: 2023-08-23 22:06:47.036137 +0000 UTC
Scopes: [moderator:manage:shield_mode moderator:manage:shoutouts]

Device Code Flow

If you wish to use Device Code Flow, the --dcf flag can be used alongside the --user-token flag.

Run the command as you would for a regular User Access Token, but include the --dcf flag:

twitch token -u -s "moderator:manage:shoutouts moderator:manage:shield_mode" --dcf

The terminal will then output information about how to authenticate in your web browser:

Started Device Code Flow login.
Use this URL to log in: https://www.twitch.tv/activate?device-code=SZPPRMFW
Use this code when prompted at the above URL: SZPPRMFW

This system will check every 5 seconds, and will expire after 30 minutes.

The application will then check Twitch's servers every 5 seconds to see if you have authenticated in your web browser. When it detects you have authenticated, it will output the tokens as expected:

2024/03/12 11:42:24 Successfully generated User Access Token.
2024/03/12 11:42:24 User Access Token: c012345asdfetc...
2024/03/12 11:42:24 Refresh Token: 012345asdfetc...
2024/03/12 11:42:24 Expires At: 2024-03-12 22:30:46.696108405 +0000 UTC
2024/03/12 11:42:24 Scopes: [moderator:manage:shield_mode moderator:manage:shoutouts]

Revoking Access Tokens

Access tokens can be revoked with:

twitch token -r 0123456789abcdefghijABCDEFGHIJ

Refreshing Access Tokens

Access tokens can be refreshed using a refresh token:

twitch token --refresh ABCDEfghij0123456789abcdefghijABCDEFGHIJ

By default, this uses the Client ID and Client Secret stored in your config file. You can override this with --client-id and --secret, as such:

twitch token --refresh ABCDEfghij0123456789abcdefghijABCDEFGHIJ --client-id uo6dggojyb8d6soh92zknwmi5ej1q2 --secret yigv8zib6nuczcoy08u8g1nxh6wjgu

When overriding the Client ID, your config file will not be updated with the new access token, client ID, or secret.

Alternate IP for User Token Webserver

If you'd like to bind the webserver used for user tokens (-u flag), you can override it with the --ip flag. For example:

twitch token -u --ip 127.0.0.1"

Alternate Port

Port 3000 on localhost is used by default when fetching User Access Tokens. The -p flag can be used to change to another port if another service is already occupying that port. For example:

twitch token -u -p 3030 -s "moderator:manage:shoutouts moderator:manage:shield_mode"

NOTE: You must update the first entry in the OAuth Redirect URLs section of your app's management page in the Developer's Application Console to match the new port number. Make sure there is no / at the end of the URL (e.g. use http://localhost:3030 and not http://localhost:3030/) and that the URL is the first entry in the list if there is more than one.

Alternate Host

If you'd like to change the hostname for one reason or another (e.g. binding to a local domain), you can use the --redirect-host to change the domain. You should not prefix it with http or https.

Example:

twitch token -u --redirect-host contoso.com

NOTE: You must update the first entry in the OAuth Redirect URLs section of your app's management page in the Developer's Application Console to match the new port number. Make sure there is no / at the end of the URL (e.g. use http://localhost:3030 and not http://localhost:3030/) and that the URL is the first entry in the list if there is more than one.

Errors

This error occurs when there's a problem with the OAuth Redirect URLs. Check in the app's management page in the Developer's Application Console to ensure the first entry is set to http://localhost:3000. Specifically, verify that your using http and not https and that the URL does not end with a /. (If you've changed ports with the -p flag, ensure those numbers match as well)

Error! redirect_mismatch
Error Details: Parameter redirect_uri does not match registered URI

Command Line Notes

Args

None.

Flags

Flag Shorthand Description Example Required? (Y/N)
--user-token -u Whether to fetch a user token or not. Default is false. token -u N
--dcf Uses Device Code Flow for your User Access Token. Can only be used with --user-token token -u --dcf N
--forceverify Sets force_verify to true, so you can check scopes and which account you are authing as. Can only be used with --user-token token -u --forceverify N
--scopes -s The space separated scopes to use when getting a user token. -s "user:read:email user_read" N
--revoke -r Instead of generating a new token, revoke the one passed to this parameter. -r 0123456789abcdefghijABCDEFGHIJ N
--validate -v Instead of generating a new token, validate the one passed to this parameter. -v 0123456789abcdefghijABCDEFGHIJ N
--refresh -R Instead of generating a new token, refresh the token associated with the Refresh Token passed to this parameter. -R ABCDEfghij0123456789abcdefghijABCDEFGHIJ N
--ip Manually set the port to be used for the User Token web server. The default binds to all interfaces. (0.0.0.0) --ip 127.0.0.1 N
--port -p Override/manually set the port for token actions. (The default is 3000) -p 3030 N
--client-id Override/manually set Client ID for token actions. By default Client ID from CLI config will be used. --client-id uo6dggojyb8d6soh92zknwmi5ej1q2 N
--secret Override/manually set Client Secret for token actions. By default Client Secret from CLI config will be used. --secret yigv8zib6nuczcoy08u8g1nxh6wjgu N
--redirect-host Override/manually set the redirect host token actions. The default is localhost --redirect-host contoso.com N

Notes

  • If you've already authorized the app, the webpage will redirect back immediately without requiring any interaction
  • You'll be asked to fill in the Client ID and Client Secret if you run the token product without having already set them