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:
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 serverDefault:TWITCH_AUTH_BASE_URL
- 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:
- 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 tokensession¶ (
Optional
[ClientSession
]) – optionally a active client session to be used for the web request to avoid having to open a new oneauth_base_url¶ (
str
) – The URL to the Twitch API auth serverDefault:TWITCH_AUTH_BASE_URL
- Return type:
- 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.
- Parameters:
session¶ (
Optional
[ClientSession
]) – optionally a active client session to be used for the web request to avoid having to open a new oneauth_base_url¶ (
str
) – The URL to the Twitch API auth serverDefault:TWITCH_AUTH_BASE_URL
- Return type:
- 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:
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 serverDefault:TWITCH_AUTH_BASE_URL
- Return type:
- Returns:
True
if revoking succeeded, otherwiseFalse
- 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:
force_verify¶ (
bool
) – If this is true, the user will always be prompted for authorization by twitchDefault: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 serverDefault:TWITCH_AUTH_BASE_URL
-
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
- 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 infoDefault:None
browser_new¶ (
int
) – controls in which way the link will be opened in the browser. See the webbrowser documentation for more infoDefault:2
- Returns:
None if callback_func is set, otherwise access_token and refresh_token
- Raises:
TwitchAPIException – if authentication fails
- Return type:
- 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/')#
- async bind()#
Bind the helper to the provided instance of twitch and sets the user authentication.
-
host: