PrivateTIDALAPIClient

class minim.api.tidal.PrivateTIDALAPIClient(*, 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] = '', 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

Private TIDAL API client.

Attention

As the private TIDAL API is not designed to be publicly accessible, this client may break without warning if TIDAL makes internal changes or be disabled and removed at any time to ensure compliance with the TIDAL Developer Terms of Service.

Parameters:

auth_flowstr or None; keyword-only

Authorization flow.

Valid values:

• None – No authentication.

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

• "device" – Device Authorization Flow.

client_idstr; keyword-only; optional

Client ID. Required unless set as system environment variable PRIVATE_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 PRIVATE_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.

Valid values: "tidal://login/auth", "https://tidal.com/login/auth".

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_handlerNone; 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 value: None – Manually paste the redirect URL into the terminal.

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

build_artwork_url	Build the URL for a TIDAL artwork.
clear_cache	Clear specific or all cache entries for this client.
close	Terminate the underlying HTTP client session.
get_country_code	Get the country code associated with the current IP address or user account.
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 information.
set_cache_enabled	Enable or disable the in-memory TTL cache for this client.

Attributes

albums	Albums API endpoints for the private TIDAL API.
artists	Artists API endpoints for the private TIDAL API.
feed	Feed API endpoints for the private TIDAL API.
mixes	Mixes API endpoints for the private TIDAL API.
pages	Pages API endpoints for the private TIDAL API.
playlists	Playlists API endpoints for the private TIDAL API.
search	Search API endpoints for the private TIDAL API.
tracks	Tracks API endpoints for the private TIDAL API.
users	Users API endpoints for the private TIDAL API.
videos	Videos API endpoint for the private TIDAL API.
AUTH_URL	Authorization endpoint.
BASE_URL	Base URL for API endpoints.
DEVICE_AUTH_URL	Device authorization endpoint.
RESOURCE_URL	URL for image resources.
TOKEN_URL	Token endpoint.

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

Authorization endpoint.

BASE_URL = 'https://api.tidal.com'

Base URL for API endpoints.

DEVICE_AUTH_URL = 'https://auth.tidal.com/v1/oauth2/device_authorization'

Device authorization endpoint.

RESOURCE_URL = 'https://resources.tidal.com'

URL for image resources.

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

Token endpoint.

albums: PrivateAlbumsAPI

Albums API endpoints for the private TIDAL API.

artists: PrivateArtistsAPI

Artists API endpoints for the private TIDAL API.

classmethod build_artwork_url(artwork_uuid: str, /, item_type: str | None = None, *, animated: bool = False, dimensions: int | str | tuple[int | str, int | str] | None = None) → str

Build the URL for a TIDAL artwork.

Parameters:

artwork_uuidstr; positional-only

TIDAL artwork UUID.

item_typestr; positional-only; optional

Type of item the artwork belongs to. If provided, the specified dimensions are validated against the allowed dimensions for the item type.

Valid values: "artist", "album", "playlist", "userProfile", "video".

animatedbool; keyword-only; default: False

Whether the artwork is animated.

dimensionsint, str, or tuple[int | str, int | str]; keyword-only; optional

Dimensions of the artwork. Use "origin" or leave blank to get artwork in its original dimensions.

Examples: "origin", 1_280, "1280", "1280x1280", (640, 360), ("640", "360").

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.

feed: PrivateFeedAPI

Feed API endpoints for the private TIDAL API.

get_country_code() → dict[str, str]

Get the country code associated with the current IP address or user account.

Returns:

country_codedict[str, str]

Country code.

Sample response: {"countryCode": "US"}.

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.

mixes: PrivateMixesAPI

Mixes API endpoints for the private TIDAL API.

open() → None

Initialize a new HTTP client session.

pages: PrivatePagesAPI

Pages API endpoints for the private TIDAL API.

playlists: PrivatePlaylistsAPI

Playlists API endpoints for the private 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.

search: PrivateSearchAPI

Search API endpoints for the private 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 information.

Warning

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

Parameters:

auth_flowstr or None; keyword-only

Authorization flow.

Valid values:

• None – No authentication.

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

• "device" – Device Authorization Flow.

client_idstr; keyword-only; optional

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

client_secretstr; keyword-only; optional

Client secret. Required for the Client Credentials flow unless set as system environment variable PRIVATE_TIDAL_API_CLIENT_SECRET.

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.

Valid values: "tidal://login/auth", "https://tidal.com/login/auth".

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.

redirect_handlerNone; 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 value: None – Manually paste the redirect URL into the terminal.

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.

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

Tracks API endpoints for the private TIDAL API.

users: PrivateUsersAPI

Users API endpoints for the private TIDAL API.

videos: PrivateVideosAPI

Videos API endpoint for the private TIDAL API.