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 (str) – The URL to the Twitch API auth server

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 (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

  • auth_base_url (str) – The URL to the Twitch API auth server

Return type:

dict

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 (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

  • auth_base_url (str) – The URL to the Twitch API auth server

Return type:

dict

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 (str) – The URL to the Twitch API auth server

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 (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

  • auth_base_url (str) – The URL to the Twitch API auth server

logger: Logger#

The logger used for OAuth related log messages

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

Authenticate with a mocked auth flow via twitch-cli

For more info see Mocking with twitch-cli

Parameters:

user_id (str) – the id of the user to generate a auth token for

Return type:

str

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:
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: Logger#

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.