Changelog

All notable changes to this project will be documented in this file.

New entries are generated from Conventional Commit messages and are grouped by commit type. Sections below that predate this are kept as they were written; the wording of a published entry never changes.

[0.12.0] - 2026-07-23

Added

Asynchronous access token refresh for AsyncClient. Authenticator.async_auth_flow and the new async_refresh_access_token refresh the token without blocking the event loop, guarded by an asyncio.Lock (bound to the running event loop) so that multiple concurrent requests trigger only a single refresh. The synchronous refresh_access_token is likewise guarded by a threading.Lock.

Changed

API requests now authenticate with the x-amz-access-token header instead of the legacy Authorization: Bearer scheme, matching the current Audible API (see #832). Header construction is centralized in the new audible.utils.build_access_token_header helper. The obsolete client-id: 0 header is no longer sent with bearer auth.

Fixed

OrjsonProvider now honors the ensure_ascii parameter. Non-ASCII characters were previously left unescaped, so the serialized output depended on which JSON library was installed.

Security

Raised the minimum versions of the optional cryptography (>=48.0.1), orjson (>=3.11.6) and ujson (>=5.13.0) dependencies to exclude releases with known vulnerabilities.

[0.11.0] - 2026-07-20

Added

Optional high-performance crypto backends for significantly improved performance:
- cryptography (Rust-accelerated, recommended) - install with pip install audible[cryptography]
- pycryptodome (C-based) - install with pip install audible[pycryptodome]
- Automatic provider selection: cryptography → pycryptodome → legacy (pure Python fallback)
- Performance improvements: 5-10x faster AES operations, 10-20x faster RSA operations, 3-5x faster PBKDF2, 5-10x faster hashing
New audible.crypto_provider module with protocol-based provider abstraction layer:
- protocols.py - Type-safe Protocol definitions for crypto operations
- cryptography_provider.py - High-performance implementation using cryptography library
- pycryptodome_provider.py - High-performance implementation using pycryptodome library
- legacy_provider.py - Pure-Python implementation wrapper (pyaes, rsa, pbkdf2)
- registry.py - Provider selection and caching with lazy initialization
RSA key caching in Authenticator for improved performance on repeated API requests
Provider override capability: pass crypto_provider parameter to Authenticator.from_file() and related methods
Process-wide default provider configuration via set_default_crypto_provider()
Optional high-performance JSON backends for significantly improved JSON serialization performance:
- orjson (Rust-based, 4-5x faster for compact JSON) - install with pip install audible[orjson]
- ujson (C-based, 2-3x faster with indent=4 support) - install with pip install audible[ujson]
- rapidjson (C++ based, 2-3x faster) - install with pip install audible[rapidjson]
- json-full extra (recommended) - install with pip install audible[json-full] for complete coverage (orjson + ujson)
- json-fast extra - install with pip install audible[json-fast] for orjson only
- Automatic provider selection: orjson → ujson → rapidjson → stdlib (pure Python fallback)
- Performance improvements: 4-5x faster compact JSON (orjson), 2-3x faster pretty-printed JSON (ujson/rapidjson)
- Smart fallback logic: orjson automatically uses ujson/rapidjson for indent=4
New audible.json_provider module with protocol-based provider abstraction layer:
- protocols.py - Type-safe Protocol definition for JSON operations
- orjson_provider.py - High-performance implementation using orjson library with smart fallback logic
- ujson_provider.py - High-performance implementation using ujson library
- rapidjson_provider.py - High-performance implementation using python-rapidjson library
- stdlib_provider.py - Standard library json wrapper (always available)
- registry.py - Provider selection and caching with auto-detection
Process-wide default JSON provider configuration via set_default_json_provider()

Changed

BREAKING (unreleased modules only): Renamed audible.json module to audible.json_provider to avoid naming conflicts with Python’s built-in json module
BREAKING (unreleased modules only): Renamed audible.crypto module to audible.crypto_provider for consistency and clarity
- Note: These modules have not been released yet, so this affects only users testing from the main branch
- All imports must be updated: from audible.json import → from audible.json_provider import
- All imports must be updated: from audible.crypto import → from audible.crypto_provider import
Replaced darglint with pydoclint for docstring validation - modern, actively maintained alternative with better Protocol support
aescipher.py now uses crypto providers for AES, PBKDF2, and hashing operations
aescipher.py now uses JSON providers for JSON serialization/deserialization
auth.py now uses crypto providers for RSA signing operations
auth.py now uses JSON providers for JSON serialization/deserialization
login.py now uses JSON providers for JSON serialization
client.py now uses JSON providers for HTTP response deserialization (replaces httpx’s internal json.loads())
metadata.py still uses stdlib json directly for separators (edge case)
Performance optimization: Request parameter lookup now uses frozenset instead of list for O(1) membership testing (previously O(n))
Performance optimization: Debug logging in client.py now uses lazy evaluation with isEnabledFor(logging.DEBUG) to avoid expensive response text formatting when debug logging is disabled
Replaced os.urandom with secrets.token_bytes for better cryptographic randomness
Improved error messages and type annotations throughout crypto layer
Improved error messages and type annotations throughout JSON layer
Simplified RSA key loading by removing redundant module-level cache (Authenticator-level caching remains)
Improved docstring quality across codebase:
- Added missing return type documentation in Protocol definitions
- Moved __init__ docstrings to class-level (Google Style Guide compliant)
- Added explicit type hints for hashmod and mac parameters
- Fixed argument order mismatches between signatures and docstrings
- Added missing exception documentation
Raise minimum supported dependency versions:
- httpx to >=0.27.2,<0.29
- Pillow to >=12.3.0, beautifulsoup4 to >=4.14.3, rsa to >=4.9.1
- Optional backends: cryptography to >=46.0.3, pycryptodome to >=3.23.0, orjson to >=3.11.5, ujson to >=5.11.0, python-rapidjson to >=1.23
Use the Python 3.11 datetime.UTC alias internally, replacing datetime.timezone.utc

Fixed

Prevent SHA-1 deprecation warning spam from cryptography library
Security vulnerabilities in crypto handling
MyPy typing issues in crypto provider implementations

Documentation

Added comprehensive installation guide for crypto extras in README and docs
Added comprehensive installation guide for JSON extras in README
Added performance benchmarks and provider selection documentation for crypto providers
Added performance benchmarks and provider selection documentation for JSON providers
Added version requirement notes (crypto features available in audible >= 0.11.0)
Added version requirement notes (JSON features available in audible >= 0.11.0)
Added example scripts for crypto provider usage
Added example scripts for JSON provider usage (examples/test_json_autodetect.py, examples/test_json_explicit.py)

Bugfix

Make register() resilient to missing fields in the registration response:
- Use tokens.get(“store_authentication_cookie”) instead of direct indexing to avoid KeyError when the server does not return this cookie.
- Only populate website_cookies when the API includes them; previously code assumed presence and could raise errors.

Misc

Drop support for Python 3.10
Add support for Python 3.14 (now requires Python >=3.11,<3.15)

[0.10.0] - 2024-09-26

Bugfix

Fix autodetect_locale function

Misc

Drop support for Python 3.8 and 3.9
Add support for Python 3.12

[0.9.1] - 2023-09-27

Bugfix

Fix login issues on brazilian marketplace.
Fix a RecursionError which occurs when checking the length of an Authenticator instance.

[0.9.0] - 2023-09-27

Bugfix

Multiple fixes for XXTEA encryption/decryption in metadata module.

Added

Add brazilian marketplace.
Login function now checks for a verification-code-form tag in login HTML page.

Changes

Drop support for Python 3.7.

Misc

First step to refactor code.
Switch project to poetry.
Using nox and ruff for tests and linting.

[0.8.2] - 2022-05-25

Changed

Allow httpx v0.23.x to fix a bug in httpx

[0.8.1] - 2022-04-20

Bugfix

fix a bug in Client.delete and AsyncClient.delete method

[0.8.0] - 2022-04-11

Added

full support of pre-Amazon accounts (e.g. refresh access token, deregister device)
Client and AsynClient now accepts session kwargs which are bypassed to the underlying httpx Client
a respone_callback can now be set to Client and AsyncClient class to allow custom preparation of response output
An absolut url (e.g. https://cde-ta-g7g.amazon.com/FionaCDEServiceEngine/sidecar) can now be passed to a client get, post, delete and put method as the path arg. So in most cases the client raw_request method is not needed anymore.

Changed

rename (and rework) Client._split_kwargs to Client._prepare_params

[0.7.2] - 2022-03-27

Bugfix

fix a bug in registration url

[0.7.1] - 2022-03-27

Added

Authenticator.from_dict to instantiate an Authenticator from dict and Authenticator.to_dict to get authentication data as dict

Bugfix

register a new device with with_username=True results in a server error due to wrong registration domain

[0.7.0] - 2021-10-25

Bugfix

make sure activation bytes has 8 bytes, otherwise append ‚0‘ in front until 8 bytes are reached
make sure metadata1 has 8 bytes, otherwise append ‚0‘ in front until 8 bytes are reached
If installed, use playwright to login with external browser. Please read here how to install playwright. Then use audible.Authenticator.from_login_external(COUNTRY_CODE) for login.
fix login issues

[0.6.0] - 2021-10-21

Bugfix

Fix a bug when searching for „resend-approval-link“ in login page

Changed

switched to auth_code_flow when login (gives an auth code instead of an access token for security purposes)
Authenticator.from_login and Authenticator.from_login_external now always register a new device
Authenticator now refreshes access_token (when needed) before deregister the device
now simulate Audible app version 3.56.2 under iOS version 15.0.0
login process now auto-detect next request method and url

Misc

Correct documentation
Update example download_books_aaxc.py
Bump httpx to v0.20.*

Remove

LoginAuthenticator and FileAuthenticator
Authenticator.register_device, Authenticator.re_login and Authenticator.re_login_external

[0.5.5] - 2021-07-22

Misc

switch from httpx 0.16.x to 0.18.x

Added

logging error messages during login

Changed

extend allowed chars by email check during login
instead of raising an exception, invalid email will now be logged as warning

Misc

Add description to the docs, to handling 2FA

[0.5.4] - 2021-02-28

Added

Provide a custom serial when login
Login with Audible username instead of Amazon account for US, UK and DE markteplace

Bugfix

register a device on Australian marketplace

Misc

Redesign Module documentation
Rework description of audible-cli package in documentation

[0.5.3] - 2021-01-25

Added

function activation_bytes.fetch_activation_sign_auth
Spain marketplace

Changed

activation_bytes.get_activation_bytes uses the new fetch_activation_sign_auth function, if signing auth method is available. Otherwise activation bytes will be fetched the old way with a player_token.

[0.5.2] - 2021-01-08

Added

Add initial cookies to login function to prevent captcha requests in most cases.

[0.5.1] - 2021-01-05

Added

Fetched activation bytes (with extract=True argument) will be stored to activation_bytes attribute of Authenticator class instance for now. Ignore existing activation bytes and force refresh with auth.get_activation_bytes(force_refresh=True)
activation_bytes will be loaded from and save to file. Saved auth files are not backward compatible to previous audible versions so keep old files save.
Add Client.raw_request and AsyncClient.raw_request method.
Provide a custom Callback with approval_callback keyword argument when login.
Add classmethod Authenticator.from_login_external and method Authenticator.re_login_external.
Add login_external function to login.py

Misc

Add description how to use pyotp with custom otp callback to docs
Add description how to use login external to docs

[0.5.0] - 2020-12-07

Added

Added support to output the whole activation blob instead of the extracted activation bytes with get_activation_bytes(extract=False, ...).
Added support to fetch website cookies for another country with Authenticator.set_website_cookies_for_country.
Added Client.put and AsyncClient.put.
Added support to solve approval alerts during login

Changed

The FileAuthenticator has been deprecated, use classmethod Authenticator.from_file instead.
The Authenticator don’t inherit from MutableMapping anymore
The Authenticator sets allowed instance attributes at creation to None, not allowed attributes will raise an Exception
The LoginAuthenticator has been deprecated, use classmethod Authenticator.from_login instead.
Changed internal code base for encryption and decryption metadata. Moved the related code to metadata.py.

Remove

deprecated AudibleAPI

Misc

Added more docstrings and type hints to code base
Added support to install Sphinx documentation dependencies with pip install audible[docs].
Added a guide to use authentication with Postman.
Rework documentation.
Added .readthedocs.yml config file
Added module description (autodoc) to docs
Uses httpx 0.16.* for now

[0.4.4] - 2020-10-25

Bugfix

Set padding=„none“ when decrypting license voucher