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

twitchAPI.oauth.refresh_access_token(refresh_token: str, app_id: str, app_secret: str)

Simple helper function for refreshing a user access token.

  • refresh_token (str) – the current refresh_token

  • app_id (str) – the id of your app

  • app_secret (str) – the secret key of your app


access_token, refresh_token

Return type

(str, str)

twitchAPI.oauth.validate_token(access_token: str) dict

Helper function for validating a user or app access token.


access_token (str) – either a user or app OAuth access token


response from the api

Return type


twitchAPI.oauth.revoke_token(client_id: str, access_token: str) bool

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

  • client_id (str) – client id belonging to the access token

  • access_token (str) – user or app OAuth access token

Return type



True if revoking succeeded, otherwise False

class twitchAPI.oauth.UserAuthenticator(twitch: twitchAPI.twitch.Twitch, scopes: List[twitchAPI.types.AuthScope], force_verify: bool = False, url: str = 'http://localhost:17563')

Simple to use client for the Twitch User authentication flow.

  • 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

  • port (int) – The port that will be used.

    Default: 17653

  • host (str) – the host the webserver will bind to.



Manually stop the flow

Return type


authenticate(callback_func=None, user_token=None)

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

  • callback_func – Function to call once the authentication finished.

  • user_token (str) – Code obtained from twitch to request the access and refresh token.


None if callback_func is set, otherwise access_token and refresh_token


TwitchAPIException – if authentication fails

Return type

None or (str, str)