User OAuth Authenticator and helper functions#

User Authenticator#

UserAuthenticator 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.

See also

This tutorial has a more detailed example how to use UserAuthenticator on a headless server: Generate a User Auth Token Headless

Code example#

from twitchAPI.twitch import Twitch
from twitchAPI.oauth import UserAuthenticator
from twitchAPI.type import AuthScope

twitch = await 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 = await auth.authenticate()
# add User authentication
await twitch.set_user_authentication(token, target_scope, refresh_token)

User Authentication Storage Helper#

UserAuthenticationStorageHelper provides a simplified way to store & reuse user tokens.

Code example#

twitch = await Twitch(APP_ID, APP_SECRET)
helper = UserAuthenticationStorageHelper(twitch, TARGET_SCOPES)
await helper.bind()"

See also

See Reuse user tokens with UserAuthenticationStorageHelper for more information.

Class Documentation#

async twitchAPI.oauth.refresh_access_token(refresh_token, app_id, app_secret, session=None, auth_base_url='https://id.twitch.tv/oauth2/')#

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

  • auth_base_url (

    Default:) – The URL to the Twitch API auth server
    Default: TWITCH_AUTH_BASE_URL

Returns:

access_token, refresh_token

Raises:
Return type:

(str, str)

async twitchAPI.oauth.validate_token(access_token, session=None, auth_base_url='https://id.twitch.tv/oauth2/')#

Helper function for validating a user or app access token.

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

Parameters:

  • access_token (

    Default:) – either a user or app OAuth access token

  • session (

    Default:) – optionally a active client session to be used for the web request to avoid having to open a new one

  • auth_base_url (

    Default:) – The URL to the Twitch API auth server
    Default: TWITCH_AUTH_BASE_URL

Return type:

Default:

Returns:

response from the api

async twitchAPI.oauth.get_user_info(access_token, session=None, auth_base_url='https://id.twitch.tv/oauth2/')#

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 (

    Default:) – a OAuth2 access token

  • session (

    Default:) – optionally a active client session to be used for the web request to avoid having to open a new one

  • auth_base_url (

    Default:) – The URL to the Twitch API auth server
    Default: TWITCH_AUTH_BASE_URL

Return type:

Default:

Returns:

response from the API

async twitchAPI.oauth.revoke_token(client_id, access_token, session=None, auth_base_url='https://id.twitch.tv/oauth2/')#

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

  • auth_base_url (

    Default:) – The URL to the Twitch API auth server
    Default: TWITCH_AUTH_BASE_URL

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', auth_base_url='https://id.twitch.tv/oauth2/')#
Parameters:

  • twitch (

    Default:) – A twitch instance

  • scopes (

    Default:) – List of the desired Auth scopes

  • force_verify (

    Default:) – If this is true, the user will always be prompted for authorization by twitch
    Default: False

  • url (

    Default:) – The reachable URL that will be opened in the browser.
    Default: http://localhost:17563

  • auth_base_url (

    Default:) – The URL to the Twitch API auth server
    Default: TWITCH_AUTH_BASE_URL

logger:
Default:#

The logger used for OAuth related log messages

document:
Default:#

The document that will be rendered at the end of the flow

port:
Default:#

The port that will be used.

Default: 17653

host:
Default:#

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 mock_authenticate(user_id)#

Authenticate with a mocked auth flow via twitch-cli

For more info see Mocking with twitch-cli

Parameters:

user_id (

Default:) – the id of the user to generate a auth token for

Return type:

Default:

Returns:

the user auth token

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 (

    Default:) – Function to call once the authentication finished.

  • user_token (

    Default:) – Code obtained from twitch to request the access and refresh token.

  • browser_name (

    Default:) – 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 (

    Default:) – 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)

class twitchAPI.oauth.UserAuthenticationStorageHelper#

Bases: object

Helper for automating the generation and storage of a user auth token.

See Reuse user tokens with UserAuthenticationStorageHelper for more detailed examples and use cases.

Basic example use:

twitch = await Twitch(APP_ID, APP_SECRET)
helper = UserAuthenticationStorageHelper(twitch, TARGET_SCOPES)
await helper.bind()
__init__(twitch, scopes, storage_path=None, auth_generator_func=None, auth_base_url='https://id.twitch.tv/oauth2/')#
logger:
Default:#

The logger used for OAuth Storage Helper related log messages

async bind()#

Bind the helper to the provided instance of twitch and sets the user authentication.