From ee44526d25646d58b55edc2c9987b449bc8d396b Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Wed, 29 Apr 2026 19:09:44 +0200 Subject: [PATCH] docs(amazon): confirm amazon_music:access scope requires device client ID Attempting to request amazon_music:access with a standard application client ID (amzn1.application-oa2-client.*) returns HTTP 400 lwa-invalid-parameter-bad-scope from the LWA authorization endpoint. The scope is gated to Amazon Music partner device client IDs. Revert scope to "profile" (working state) and document the confirmed blocker with the exact error. Path forward: Amazon Music partner registration for a device client ID; one-line change to AmazonScopes when available. Co-Authored-By: Claude Sonnet 4.6 --- docs/concepts/amazon-music-oauth.md | 4 ++-- pkg/service/amazon/service.go | 5 ++++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/concepts/amazon-music-oauth.md b/docs/concepts/amazon-music-oauth.md index 50a2973..1770072 100644 --- a/docs/concepts/amazon-music-oauth.md +++ b/docs/concepts/amazon-music-oauth.md @@ -12,7 +12,7 @@ All eight implementation steps are done. The OAuth flow (account linking, token However, real-world testing shows that the speaker then calls `https://music-api.amazon.com/` with that token and receives a `401 Unauthorized` (no redirect to a regional endpoint). This means the token does not carry the scopes required to access the Amazon Music streaming API. -**Root cause:** `music-api.amazon.com` is a partner-gated API. Standard Login with Amazon apps only receive `profile` scope. Amazon Music streaming requires additional `music::*` scopes that are only granted to registered Amazon Music partners (such as Bose was). Without a partner agreement, end users cannot obtain these scopes through a self-hosted LWA app. +**Root cause (confirmed):** Amazon Music streaming requires the `amazon_music:access` scope, which is only available to **device client IDs** — a separate credential type obtained through Amazon's Music partner programme. Standard Login with Amazon application client IDs (`amzn1.application-oa2-client.*`) cannot request this scope: attempting to include it in the authorization URL returns `lwa-invalid-parameter-bad-scope` (HTTP 400) from the LWA authorization endpoint. Bose would have held a device client ID as a registered Amazon Music partner. **What still works:** - Account linking and token storage @@ -22,7 +22,7 @@ However, real-world testing shows that the speaker then calls `https://music-api **What does not work:** - Actual music playback — the speaker's `AmazonClient` cannot authenticate to `music-api.amazon.com` with a standard LWA token -**Path forward:** If Amazon opens up `music::*` scopes to developer apps, or if a partner token is obtained through other means, the infrastructure is ready to use without further code changes. The `site_id` field (see below) is a secondary open question that may also affect regional routing once the scope issue is resolved. +**Path forward:** Obtaining a device client ID requires registering with Amazon's Music partner programme. If such a credential is obtained, the only code change needed is swapping the `client_id`/`client_secret` for the device credentials and adding `amazon_music:access` to `AmazonScopes` in `pkg/service/amazon/service.go` — everything else is already in place. The `site_id` field is a secondary open question that may also affect regional routing once the scope issue is resolved. --- diff --git a/pkg/service/amazon/service.go b/pkg/service/amazon/service.go index fa18fb6..8885268 100644 --- a/pkg/service/amazon/service.go +++ b/pkg/service/amazon/service.go @@ -26,7 +26,10 @@ const ( // AmazonProfileURL is the LWA user profile endpoint. AmazonProfileURL = "https://api.amazon.com/user/profile" // AmazonScopes are the OAuth scopes for account linking. - // Expand to "music::*" scopes once Amazon Music API access is available. + // amazon_music:access is required for music-api.amazon.com but is only available + // to device client IDs (Amazon Music partner apps), not standard application + // client IDs (amzn1.application-oa2-client.*). Requesting it returns a 400 + // lwa-invalid-parameter-bad-scope error from the LWA authorization endpoint. AmazonScopes = "profile" )