spotifywebapipython.oauthcli.authclient

class AuthClient:

OAuth2 Authorization client class.

AuthClient( authorizationType: str, authorizationUrl: str = None, tokenUrl: str = None, scope: str = None, clientId: str = None, clientSecret: str = None, oauth2Client: oauthlib.oauth2.rfc6749.clients.base.Client = None, oauth2Session: requests_oauthlib.oauth2_session.OAuth2Session = None, tokenProviderId: str = None, tokenProfileId: str = None, tokenStorageDir: str = None, tokenUpdater: Callable = None)

Initializes a new instance of the class.

Arguments:
  • authorizationType (str): OAuth2 authorization type title (e.g. "Client Credentials", etc).
  • authorizationUrl (str): URL used to authorize the requested access.
  • tokenUrl (str): URL used to request an access token.
  • scope (str | list[str]): A space-delimited list of scopes you wish to request access to.
    If no scopes are specified, authorization will be granted only to access publicly available information.
  • clientId (str): The unique identifier of the application.
  • clientSecret (str): The application's secret key, used to authorize your Web API or SDK calls.
  • oauth2Client (Client): OAuth2 Client instance to use for this request.
    If null, a new WebApplicationClient will be created with the specified clientId and scope argument values.
  • oauth2Session (requests_oauthlib.oauth2_session.OAuth2Session): A OAuth2Session instance to use for this request.
    If null, a new 'requests_oauthlib.oauth2_session.OAuth2Session' will be created with the specified clientId and scope argument values.
  • tokenProviderId (str): Provider identifier used when storing the token to disk. A null value will default to Shared.
    Default: Shared
  • tokenProfileId (str): Profile identifier used when storing the token to disk.
    A null value will default to Shared.
    Default: Shared
  • tokenStorageDir (str): The directory path that will contain the tokens.json file.
    A null value will default to the platform specific storage location:
    Example for Windows OS = C:\ProgramData\SpotifyWebApiPython
  • tokenUpdater (Callable): A method to call when a token needs to be refreshed by an external provider.
    The defined method is called with no parameters, and should return a token dictionary.
    Default is null.
AuthorizationType: str

OAuth2 authorization type title (e.g. "Client Credentials", etc).

AuthorizationUrl: str

Url used to request user authorization permission for an authorization token.

ClientId: str

The unique identifier of the application.

CodeVerifier: str

The code verifier string used as part of the token request authorization process.

According to the PKCE standard, a code verifier is a high-entropy cryptographic random string with a length between 43 and 128 characters (the longer the better). It can contain letters, digits, underscores, periods, hyphens, or tildes.

IsAuthorized: bool

Indicates whether this session has an OAuth token 'access_token' value or not.

If True, you can reasonably expect OAuth-protected requests to the resource to succeed.

If False, you need the user to go through the OAuth authentication dance before OAuth-protected requests to the resource will succeed.

Session: requests_oauthlib.oauth2_session.OAuth2Session

OAuth 2 extension to the requests.Session class.

Supports any grant type adhering to oauthlib.oauth2.Client spec including the four core OAuth 2 grants.

Can be used to create authorization urls, fetch tokens and access protected resources using the requests.Session class interface you are used to.

TokenProfileId: str

Profile identifier used when loading / storing the token from / to disk.

TokenUrl: str

Url used to request or renew an authorization token.

def Logout(self):

Removes a stored token, but does not clear the current session.

Warning: a request with the current session can refresh and save the token, making this call ineffective.

def process_url(self, api: str) -> str:
def request(self, method: str, api: str, **kwargs) -> object:
def get(self, api: str, **kwargs):
def post(self, api: str, **kwargs):
def put(self, api: str, **kwargs):
def patch(self, api: str, **kwargs):
def delete(self, api: str, **kwargs):
def head(self, api: str, **kwargs):
def options(self, api: str, **kwargs):
def authorization_url(self, **kwargs):

Constructs the authorization url, complete with all querystring parameters.

Arguments:
  • **kwargs Keyword arguments for the authorization type.
Returns:

The authorization url querystring and a generated state value.

def FetchToken(self, **kwargs) -> dict:

Fetch an access token from the token endpoint.

Arguments:
  • **kwargs: Additional keyword arguments to add to the
Returns:

A token dictionary.

def HasScopeChanged(self, token: dict, scope: str = None) -> bool:

Indicates whether the scope has changed between this session and the authorization access token scope values.

Arguments:
  • token (dict): The authorization access token dictionary to check the scope of.
  • scope (str | list[str]): A space-delimited list of scope identifiers you wish to request access to.

If True, you need the user to go through the OAuth authentication dance before OAuth-protected requests to the resource will succeed.

If False, then you can reasonably expect OAuth-protected requests to the resource to succeed.

def AuthorizeWithConsole( self, authorization_prompt_message='Please visit this URL to authorize this application: {url}', open_browser=True, code_message='Enter the authorization code: ', token_audience=None, force: bool = False, token_test: Optional[Callable] = None, **kwargs):

Executes the authorization flow without starting a web server.

Note that you must have 'urn:ietf:wg:oauth:2.0:oob' as a redirect URI value in the provider app settings for this to work.

Arguments:
  • authorization_prompt_message (str | None): The message to display that will inform the user to navigate to the authorization URL. If null, then no message is displayed.
  • open_browser (bool): True to open the authorization URL in the user's browser; otherwise, False to not open a browser.
  • code_message (str): The message to display in the console prompting the user to enter the authorization code.
  • token_audience (str): Passed along with the request for an access token.
    It determines the endpoints with which the token can be used.
    Default is null.
  • force (bool): True to authorize, even if we already have a token; otherwise, False to only authorize if the token is not authorized, has expired, or the scope has changed.
  • token_test (Callable): Function that receives this object for a param, makes a call, and returns the response.
  • kwargs: Additional keyword arguments passed through to authorization_url.
Returns:

The OAuth 2.0 credentials for the user.

def AuthorizeWithServer( self, host: Optional[str] = None, bind_addr: Optional[int] = None, port: Union[int, list[int]] = 8080, authorization_prompt_message: Optional[str] = 'Please visit this URL to authorize this application: {url}', success_message: str = 'The authentication flow has completed; you may close this window (or tab).', open_browser: bool = True, redirect_uri_trailing_slash: bool = True, timeout_seconds: Optional[int] = 120, token_audience: Optional[str] = None, force: bool = False, token_test: Optional[Callable] = None, **kwargs):

Executes the authorization flow by starting a temporary local web server to listen for the authorization response.

Note that you must have 'http://localhost:8080/' as a redirect URI value in the provider app settings for this to work.

The server strategy instructs the user to open the authorization URL in their browser and will attempt to automatically open the URL for them. It will start a local web server to listen for the authorization response. Once authorization is complete the authorization server will redirect the user's browser to the local web server. The web server will get the authorization code from the response and shutdown. The code is then exchanged for a token.

Arguments:
  • host (str): The hostname for the local redirect server. This will be served over http, not https.
  • bind_addr (str): Optionally provide an ip address for the redirect server to listen on when it is not the same as host (e.g. in a container).
    Default value is None, which means that the redirect server will listen on the ip address specified in the host parameter.
  • port (int / list[int]): The port for the local redirect server.
    If a list, it would find the first open port in the range.
  • authorization_prompt_message (str | None): The message to display that will inform the user to navigate to the authorization URL. If null, then no message is displayed.
  • success_message (str): The message to display in the web browser that the authorization flow is complete.
  • open_browser (bool): True to open the authorization URL in the user's browser; otherwise, False to not open a browser.
  • redirect_uri_trailing_slash (bool): True to add trailing slash when constructing the redirect_uri; otherwise, False to not add a trailing slash.
    Default value is True.
  • timeout_seconds (int): If set, an error will be raised after the timeout value if the user did not respond to the authorization request. The value is in seconds.
    When set to None there is no timeout.
    Default value is 120 (2 minutes).
  • token_audience (str): Passed along with the request for an access token.
    It determines the endpoints with which the token can be used.
    Default is null.
  • force (bool): True to authorize, even if we already have a token; otherwise, False to only authorize if the token is not authorized, has expired, or the scope has changed.
  • token_test (Callable): Function that receives this object for a param, makes a call, and returns the response.
  • kwargs: Additional keyword arguments passed through to authorization_url.
Returns:

The OAuth 2.0 credentials for the user.

def RefreshToken(self, **kwargs) -> dict:

Refreshes the current session token.

If a TokenUpdater callable was specified, then the token is refreshed externally by the callable function.

Otherwise, the session refresh_token method is invoked using the refresh token value.

Arguments:
  • **kwargs: Additional keyword arguments to include in the token request.
Returns:

A token dictionary.