Skip to content

Implement V2 API authentication with HMAC-SHA1 signing - #101

Merged
piekstra merged 1 commit into
mainfrom
piekstra/v2-auth-signing
Feb 7, 2026
Merged

piekstra merged 1 commit into
mainfrom
piekstra/v2-auth-signing

Conversation

@piekstra

@piekstra piekstra commented Feb 7, 2026

Copy link
Copy Markdown
Owner

Summary

Migrates from the deprecated V1 cloud API to the V2 API protocol used by the current Kasa Android app (v3.4.451). This is the core auth infrastructure for v5.0.

New modules:

  • signing.py - HMAC-SHA1 request signing using AccessKey/SecretKey extracted from the Kasa APK
  • exceptions.py - Custom exception hierarchy: TPLinkCloudError, TPLinkAuthError, TPLinkMFARequiredError, TPLinkTokenExpiredError, TPLinkDeviceOfflineError
  • certs/ - Bundled TP-Link private CA certificate chain for SSL verification with V2 API servers

Updated modules:

  • client.py - V2 login flow with regional URL discovery, MFA callback support, refresh token management, HMAC-signed requests
  • device_client.py - HMAC signing and TP-Link CA SSL on all device passthrough requests
  • device_manager.py - New mfa_callback parameter, refresh token storage/retrieval, automatic token refresh on expiry
  • api_response.py - Added error_code and msg properties
  • __init__.py - Export new exception classes
  • setup.py - Bundle certs as package data, require Python 3.10+

Key technical details:

  • V2 login: getAccountStatusAndUrl → regional URL → login (flat JSON body, no method/params wrapper)
  • Device operations unchanged: still use V1 JSON format ({"method": "passthrough", ...}) on root path, but with V2 signing headers
  • All requests include HMAC-SHA1 signature in X-Authorization header and Content-MD5 header
  • Query parameters match the Kasa app's OkHttp interceptor chain (C29914q)

Verified working end-to-end against the live TP-Link API:

  • Login with regional URL discovery
  • Device listing (17 parent devices, 35 total with children)
  • Device control (passthrough commands)

Closes #83, #84, #85, #86, #87, #88, #96

Test plan

  • V2 login succeeds with real credentials
  • Regional URL discovery works (returns n-use1-wap.tplinkcloud.com)
  • Token and refresh token returned from login
  • Device listing returns all 17 devices
  • Device passthrough commands work (get_sys_info, set_relay_state)
  • Creating TPLinkDeviceManager without credentials still works (regression TPLinkDeviceManager does not initialise _auth_token unless username and password are provided #75)
  • All imports resolve correctly
  • Signing module produces valid HMAC-SHA1 signatures
  • CA cert bundle loads and SSL verification succeeds
  • MFA flow (requires 2FA-enabled account to test)
  • Token refresh flow (requires expired token)
  • Wiremock tests need updating for V2 endpoints (Update mock API server for V2 testing #97)

Migrate from the deprecated V1 API to the V2 API protocol used by
the current Kasa Android app. The V2 API requires HMAC-SHA1 request
signing on all requests and uses a different login flow with regional
URL discovery.

New modules:
- signing.py: HMAC-SHA1 request signing (AccessKey/SecretKey from APK)
- exceptions.py: TPLinkAuthError, TPLinkMFARequiredError,
  TPLinkTokenExpiredError, TPLinkDeviceOfflineError
- certs/: Bundled TP-Link private CA chain for SSL verification

Changes:
- client.py: V2 login flow (regional URL discovery -> login),
  MFA callback support, refresh token support, signed requests
- device_client.py: HMAC signing + SSL with TP-Link CA on all
  device passthrough requests
- device_manager.py: MFA callback parameter, refresh token storage,
  automatic token refresh on expiry
- api_response.py: Added error_code and msg properties
- __init__.py: Export new exception classes
- setup.py: Bundle certs as package data, require Python 3.10+

Device operations still use V1 JSON format (method/params wrapper)
on the root path, but with V2 signing headers and query parameters.

Closes #83, closes #84, closes #85, closes #86, closes #87,
closes #88, closes #96
@piekstra piekstra added this to the 5.0.0 - V2 API Support milestone Feb 7, 2026
@piekstra
piekstra merged commit 11663ff into main Feb 7, 2026
0 of 3 checks passed
@piekstra
piekstra deleted the piekstra/v2-auth-signing branch February 7, 2026 06:50
@github-project-automation github-project-automation Bot moved this from Todo to Done in tplink-cloud-api v5.0 Feb 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

Add HMAC-SHA1 request signing module

1 participant