User OAuth Authenticator and helper functions#

This tool is an alternative to various online services that give you a user auth token. It provides non-server and server options.

Requirements for non-server environment#

Since this tool opens a browser tab for the Twitch authentication, you can only use this tool on enviroments that can open a browser window and render the twitch.tv website.

For my authenticator you have to add the following URL as a “OAuth Redirect URL”: http://localhost:17563 You can set that here in your twitch dev dashboard.

Requirements for server environment#

You need the user code provided by Twitch when the user logs-in at the url returned by return_auth_url().

Create the UserAuthenticator with the URL of your webserver that will handle the redirect, and add it as a “OAuth Redirect URL” You can set that here in your twitch dev dashboard.

Code example#from twitchAPI.twitch import Twitch
from twitchAPI.oauth import UserAuthenticator
from twitchAPI.types import AuthScope

twitch = Twitch('my_app_id', 'my_app_secret')

target_scope = [AuthScope.BITS_READ]
auth = UserAuthenticator(twitch, target_scope, force_verify=False)
# this will open your default browser and prompt you with the twitch verification website
token, refresh_token = auth.authenticate()
# add User authentication
twitch.set_user_authentication(token, target_scope, refresh_token)

Class Documentation#

async twitchAPI.oauth.refresh_access_token(refresh_token, app_id, app_secret, session=None)#

Simple helper function for refreshing a user access token.

Parameters:

refresh_token (str) – the current refresh_token
app_id (str) – the id of your app
app_secret (str) – the secret key of your app
session (ClientSession) – optionally a active client session to be used for the web request to avoid having to open a new one

Returns:

access_token, refresh_token

Raises:

InvalidRefreshTokenException – if refresh token is invalid
UnauthorizedException – if both refresh and access token are invalid (eg if the user changes their password of the app gets disconnected)

Return type:

(str, str)

async twitchAPI.oauth.validate_token(access_token, session=None)#

Helper function for validating a user or app access token.

https://dev.twitch.tv/docs/authentication/validate-tokens

Parameters:

access_token (str) – either a user or app OAuth access token
session (Optional[ClientSession]) – optionally a active client session to be used for the web request to avoid having to open a new one

Return type:

dict

Returns:

response from the api

async twitchAPI.oauth.get_user_info(access_token, session=None)#

Helper function to get claims information from an OAuth2 access token.

https://dev.twitch.tv/docs/authentication/getting-tokens-oidc/#getting-claims-information-from-an-access-token

Parameters:

access_token (str) – a OAuth2 access token
session (Optional[ClientSession]) – optionally a active client session to be used for the web request to avoid having to open a new one

Return type:

dict

Returns:

response from the API

async twitchAPI.oauth.revoke_token(client_id, access_token, session=None)#

Helper function for revoking a user or app OAuth access token.

https://dev.twitch.tv/docs/authentication/revoke-tokens

Parameters:

client_id (str) – client id belonging to the access token
access_token (str) – user or app OAuth access token
session (ClientSession) – optionally a active client session to be used for the web request to avoid having to open a new one

Return type:

bool

Returns:

True if revoking succeeded, otherwise False

class twitchAPI.oauth.UserAuthenticator#

Bases: object

Simple to use client for the Twitch User authentication flow.

__init__(twitch, scopes, force_verify=False, url='http://localhost:17563')#

Parameters:

twitch (Twitch) – A twitch instance
scopes (List[AuthScope]) – List of the desired Auth scopes
force_verify (bool) – If this is true, the user will always be prompted for authorization by twitch
Default: False
url (str) – The reachable URL that will be opened in the browser.
Default: http://localhost:17563

document: str#: The document that will be rendered at the end of the flow

port: int#: The port that will be used.
Default: 17653

host: str#: the host the webserver will bind to.
Default: 0.0.0.0

stop()#

Manually stop the flow

Return type:: None

return_auth_url()#: Returns the URL that will authenticate the app, used for headless server environments.

async authenticate(callback_func=None, user_token=None, browser_name=None, browser_new=2)#

Start the user authentication flow

If callback_func is not set, authenticate will wait till the authentication process finished and then return the access_token and the refresh_token If user_token is set, it will be used instead of launching the webserver and opening the browser

Parameters:

callback_func (Optional[Callable[[str, str], None]]) – Function to call once the authentication finished.
user_token (Optional[str]) – Code obtained from twitch to request the access and refresh token.
browser_name (Optional[str]) – The browser that should be used, None means that the system default is used. See the webbrowser documentation for more info
Default:None
browser_new (int) – controls in which way the link will be opened in the browser. See the webbrowser documentation for more info
Default:2

Returns:

None if callback_func is set, otherwise access_token and refresh_token

Raises:

TwitchAPIException – if authentication fails

Return type:

None or (str, str)