TIDALAPIClient

class minim.api.tidal.TIDALAPIClient(*, auth_flow: str, client_id: str | None = None, client_secret: str | None = None, user_identifier: str | None = None, redirect_uri: str | None = None, scopes: str | Collection[str] = '', access_token: str | None = None, refresh_token: str | None = None, expires_at: str | datetime | None = None, redirect_handler: str | None = None, open_browser: bool = False, enable_cache: bool = True, store_tokens: bool = True, user_agent: str | None = None)

Bases: BaseTIDALAPIClient

TIDAL API client.

Parameters:

auth_flowstr; keyword-only

Authorization flow.

Valid values:

• "pkce" – Authorization Code Flow with Proof Key for Code Exchange (PKCE).

• "client_credentials" – Client Credentials Flow.

client_idstr; keyword-only; optional

Client ID. Required unless set as system environment variable TIDAL_API_CLIENT_ID or stored in the local token storage.

client_secretstr; keyword-only; optional

Client secret. Required for the Client Credentials flow unless set as system environment variable TIDAL_API_CLIENT_SECRET or stored in the local token storage.

user_identifierstr; keyword-only; optional

Identifier for the user account. Used when store_tokens=True to distinguish between multiple accounts for the same client ID and authorization flow.

If specified, it is used with the client ID and authorization flow to locate a matching stored token. If none is found, a new token is obtained and stored under this identifier.

If not specified, the most recently accessed token for the client ID and authorization flow is used. If none exists, a new token is obtained and stored using the TIDAL user ID acquired from a successful authorization.

Prefixing the identifier with a tilde (~) bypasses token retrieval, forces reauthorization, and stores the new token under the suffix.

redirect_uristr; keyword-only; optional

Redirect URI. Required for the Authorization Code with PKCE flow.

scopesstr or Collection[str]; keyword-only; optional

Authorization scopes requested by the client to access user resources.

See also

resolve_scopes() – Resolve scope categories and/or substrings into a set of scopes.

access_tokenstr; keyword-only; optional

Access token. If provided, the authorization process is bypassed, and automatic token refresh is enabled when relevant metadata (refresh token, expiry, etc.) is also supplied.

refresh_tokenstr; keyword-only; optional

Refresh token for renewing the access token. If not provided, the user will be reauthorized via the specified authorization flow when the access token expires.

expires_atstr or datetime.datetime; keyword-only; optional

Expiration time of the access token. If a string, it must be in ISO 8601 format (%Y-%m-%dT%H:%M:%SZ).

redirect_handlerstr or None; keyword-only; optional

Backend for handling redirects during the authorization flow. Redirect handling is only available for hosts localhost, 127.0.0.1, or ::1.

Valid values:

• None – Show authorization URL in and have the user

  manually paste the redirect URL into the terminal.

• "http.server" – Run a HTTP server to intercept the redirect after user authorization in any local browser.

• "playwright" – Use a Playwright Firefox browser to complete the user authorization.

open_browserbool; keyword-only; default: False

Whether to automatically open the authorization URL in the default web browser for the Authorization Code with PKCE flow. If False, the URL is printed to the terminal.

enable_cachebool; keyword-only; default: True

Whether to enable an in-memory time-to-live (TTL) cache with a least recently used (LRU) eviction policy for this client. If True, responses from semi-static endpoints are cached for one minute to one day, depending on their expected update frequency.

See also

clear_cache() – Clear specific or all cache entries for this client.

store_tokensbool; keyword-only; default: True

Whether to enable the local token storage for this client. If True, existing access tokens are retrieved when found in local storage, and newly acquired tokens and their metadata are stored for future retrieval. If False, the client neither retrieves nor stores access tokens.

See also

get_tokens() – Retrieve specific or all stored access tokens for this client.

remove_tokens() – Remove specific or all stored access tokens for this client.

user_agentstr; keyword-only; optional

User-Agent value to include in the headers of HTTP requests.

Methods

clear_cache	Clear specific or all cache entries for this client.
close	Terminate the underlying HTTP client session.
get_tokens	Retrieve specific or all access tokens and their metadata for this client from local storage.
open	Initialize a new HTTP client session.
remove_tokens	Remove specific or all access tokens and their metadata for this client from local storage.
resolve_scopes	Resolve one or more scope categories or substrings into a set of scopes.
set_access_token	Set or update the access token and its related metadata.
set_auth_flow	Set or update the authorization flow and related parameters.
set_cache_enabled	Enable or disable the in-memory TTL cache for this client.

Attributes

albums	Albums API endpoints for the TIDAL API.
artists	Artists and Artist Roles API endpoints for the TIDAL API.
artworks	Artworks API endpoints for the TIDAL API.
playlists	Playlists API endpoints for the TIDAL API.
providers	Providers API endpoints for the TIDAL API.
rules	Usage Rules API endpoints for the TIDAL API.
search	Search Results and Search Suggestions API endpoints for the TIDAL API.
tracks	Tracks API endpoints for the TIDAL API.
users	User Collections, User Entitlements, User Recommendations, and Users API endpoints for the TIDAL API.
videos	Videos API endpoints for the TIDAL API.
AUTH_URL	Authorization endpoint.
BASE_URL	Base URL for API endpoints.
DEVICE_AUTH_URL	Device authorization endpoint.
TOKEN_URL	Token endpoint.

AUTH_URL = 'https://login.tidal.com/authorize'

Authorization endpoint.

BASE_URL = 'https://openapi.tidal.com/v2'

Base URL for API endpoints.

DEVICE_AUTH_URL = None

Device authorization endpoint.

TOKEN_URL = 'https://auth.tidal.com/v1/oauth2/token'

Token endpoint.

albums: AlbumsAPI

Albums API endpoints for the TIDAL API.

artists: ArtistsAPI

Artists and Artist Roles API endpoints for the TIDAL API.

artworks: ArtworksAPI

Artworks API endpoints for the TIDAL API.

clear_cache(endpoint_methods: str | Callable[..., Any] | Collection[str | Callable[..., Any]] | None = None, /) → None

Clear specific or all cache entries for this client.

Warning

If endpoint_methods is not provided, all cache entries are cleared.

Parameters:

endpoint_methodsstr, Callable, or Collection[str | Callable]; positional-only; optional

Endpoint methods whose cache entries should be cleared.

close() → None

Terminate the underlying HTTP client session.

classmethod get_tokens(*, auth_flows: str | Collection[str] | None = None, client_ids: str | Collection[str] | None = None, user_identifiers: str | Collection[str] | None = None) → list[dict[str, Any]] | None

Retrieve specific or all access tokens and their metadata for this client from local storage.

Parameters:

auth_flowsstr or Collection[str]; keyword-only; optional

Authorization flows.

client_idsstr or Collection[str]; keyword-only; optional

Client IDs.

user_identifiersstr or Collection[str]; keyword-only; optional

Identifiers for the user accounts.

open() → None

Initialize a new HTTP client session.

playlists: PlaylistsAPI

Playlists API endpoints for the TIDAL API.

providers: ProvidersAPI

Providers API endpoints for the TIDAL API.

classmethod remove_tokens(*, auth_flows: str | Collection[str] | None = None, client_ids: str | Collection[str] | None = None, user_identifiers: str | Collection[str] | None = None) → None

Remove specific or all access tokens and their metadata for this client from local storage.

Warning

If none of auth_flows, client_ids, or user_identifiers are provided, all tokens for this client will be removed from local storage.

Parameters:

auth_flowsstr or Collection[str]; keyword-only; optional

Authorization flows.

client_idsstr or Collection[str]; keyword-only; optional

Client IDs.

user_identifiersstr or Collection[str]; keyword-only; optional

Identifiers for the user accounts.

classmethod resolve_scopes(matches: str | Collection[str] | None = None) → set[str]

Resolve one or more scope categories or substrings into a set of scopes.

Parameters:

matchesstr or Collection[str]; optional

Substrings to match in the available scopes. If not specified, all available scopes are returned.

Returns:

scopesset[str]

Authorization scopes.

rules: RulesAPI

Usage Rules API endpoints for the TIDAL API.

search: SearchAPI

Search Results and Search Suggestions API endpoints for the TIDAL API.

set_access_token(access_token: str | None, /, token_type: str | None = 'Bearer', *, refresh_token: str | None = None, expires_at: str | datetime | None = None) → None

Set or update the access token and its related metadata.

Warning

Calling this method replaces all existing values with the provided parameters. Parameters not provided explicitly will be overwritten by their default values.

Parameters:

access_tokenstr or None; positional-only

Access token.

Important

If the access token was acquired via a different authorization flow or client, call set_auth_flow() first to ensure that all other relevant authorization parameters are set correctly.

token_typestr or None; default: "Bearer"

Type of the access token.

refresh_tokenstr; keyword-only; optional

Refresh token for renewing the access token. If not provided, the user will be reauthorized via the current authorization flow when the access token expires.

expires_atstr or datetime.datetime; keyword-only; optional

Expiration time of the access token. If a string, it must be in ISO 8601 format (%Y-%m-%dT%H:%M:%SZ).

set_auth_flow(auth_flow: str | None, /, *, client_id: str | None = None, client_secret: str | None = None, user_identifier: str | None = None, redirect_uri: str | None = None, scopes: str | Collection[str] = '', redirect_handler: str | None = None, open_browser: bool = False, store_tokens: bool = True, authenticate: bool = True) → None

Set or update the authorization flow and related parameters.

Warning

Calling this method replaces all existing values with the provided parameters. Parameters not provided explicitly will be overwritten by their default values.

Parameters:

auth_flowstr or None; keyword-only

Authorization flow.

Valid values:

• None – No authentication.

• "auth_code" – Authorization Code Flow.

• "pkce" – Authorization Code Flow with Proof Key for Code Exchange (PKCE).

• "client_credentials" – Client Credentials Flow.

• "device" – Device Authorization Flow.

• "implicit" – Implicit Grant Flow.

client_idstr; keyword-only; optional

Client ID. Required unless set as a system environment variable.

client_secretstr; keyword-only; optional

Client secret. Required for the Authorization Code, Client Credentials, and Resource Owner Password Credential flows unless set as a system environment variable.

user_identifierstr; keyword-only; optional

Identifier for the user account. Used when store_tokens=True to distinguish between multiple accounts for the same client ID and authorization flow.

If specified, it is used with the client ID and authorization flow to locate a matching stored token. If none is found, a new token is obtained and stored under this identifier.

If not specified, the most recently accessed token for the client ID and authorization flow is used. If none exists, a new token is obtained and stored using a user identifier (e.g., user ID) acquired from a successful authorization.

Prefixing the identifier with a tilde (~) bypasses token retrieval, forces reauthorization, and stores the new token under the suffix.

redirect_uristr; keyword-only; optional

Redirect URI. Required for the Authorization Code, Authorization Code with PKCE, and Implicit Grant flows.

scopesstr or Collection[str]; keyword-only; optional

Authorization scopes requested by the client to access user resources.

redirect_handlerstr or None; keyword-only; optional

Backend for handling redirects during the authorization flow. Redirect handling is only available for hosts localhost, 127.0.0.1, or ::1.

Valid values:

• None – Show authorization URL in and have the user manually paste the redirect URL into the terminal.

• "http.server" – Run a HTTP server to intercept the redirect after user authorization in any local browser.

• "playwright" – Use a Playwright Firefox browser to complete the user authorization.

open_browserbool; keyword-only; default: False

Whether to automatically open the authorization URL in the default web browser for the Authorization Code, Authorization Code with PKCE, and Implicit Grant flows. If False, the URL is printed to the terminal.

store_tokensbool; keyword-only; default: True

Whether to enable the local token storage for this client. If True, existing access tokens are retrieved when found in local storage, and newly acquired tokens and their metadata are stored for future retrieval. If False, the client neither retrieves nor stores access tokens.

See also

get_tokens() – Retrieve specific or all stored access tokens for this client.

remove_tokens() – Remove specific or all stored access tokens for this client.

authenticatebool; keyword-only; default: True

Whether to immediately initiate the authorization flow to acquire an access token.

Important

Unless set_access_token() is called immediately after, this should be left as True to ensure the client’s existing token is compatible with the new authorization flow and/or scopes.

set_cache_enabled(enable: bool, /) → None

Enable or disable the in-memory TTL cache for this client.

Parameters:

enablebool; positional-only

Whether to enable the cache.

tracks: TracksAPI

Tracks API endpoints for the TIDAL API.

users: UsersAPI

User Collections, User Entitlements, User Recommendations, and Users API endpoints for the TIDAL API.

videos: VideosAPI

Videos API endpoints for the TIDAL API.