From the Amazon Music Api Developer program, explaining the change from API 1.0 to new Oauth 2.0 system, still in closed Beta for development, but the basic method, if not configured, seems to automatically convert to the lowest authority-authorisation (if that makes sense) which is simply library read. You can read and play everything but cannot manage any of the following (see table below)
This is determined by new/updated authorisation as defined by scopes. Unless explicitly requested, with additional scopes in the below format, Amazon Music will return the lowest authority access, the basic library:read scope. See below.
Now, how can we make sure that Sonos is sending the proper requests with the proper scope? Because mine certainly isn't. I can't do anything with my library: here's what songs, when playing, look like. Can only "View Artist on Amazon" - seemingly not even album! Can't add to library, favourite/like/upvote song (or dislike/downvote), create or manage playlists, nothing. It's really a pain to get recommended a good song and have to find my device and load up the Amazon app (and get warned not to play on two devices at once) I do all my listening via Sonos, I need library management. Without Last.Fm (which I have to pay for, albeit not a lot, but still £4.5/$6 per month) I'd have a nightmare tracking my library, it would be totally unworkable.
So, here's the solution, I'm pretty sure this is what we need to look at. I'm going to see if I can examine the same for Apple but they are a notoriously dreadful closed-source junk company (yes, I'm biased, they produce overpriced garbage - but their Music has the best quality and largest availability) but maybe I'll get lucky and find access to their version or find out why Sonos won't allow management of Apple Music either (to confirm, it allows Spotify and Deezer management pretty much in full, I think)
1. OAuth 2.0 Protocol
The Amazon Music Web Service API uses Login With Amazon (LWA) which is based on the OAuth 2.0 authorization framework to securely identify clients and end-users. With this open protocol, a client wishing to access a protected resource must contact an authorization server to obtain an access token. Clients must transmit this access token when making subsequent protected resource requests.
2. Login With Amazon (LWA)
Note: Amazon Music Web APIs are currently in beta. To enable access to Amazon Music developer API please contact your Amazon Business Development representative.
Login with Amazon (LWA) provides the authorization server for the Amazon Music API. LWA is a separate service from the core Amazon Music Service, and so its API may have different formats, structure, and requirements from the Amazon Music API documented here.
To use LWA, your business first needs to create an Amazon developer account, then create a Security Profile ID. Click here to learn how to create a Login With Amazon account.
To learn how to use Login With Amazon to request an authentication token, click here.
3. Calling LWA for use with Amazon Music
3A. SCOPES DESCRIPTION
The Security Profil ID(s) used by Music client applications must be enabled by the Amazon Music Service in order for authorization to be successful. Access to particular API endpoints are restricted by scope. A certain set of scopes are granted by default as part of onboarding. If you find you need access to a scope which you do not currently have, reach out to your Amazon Music contact.
When logging in, users will be prompted for consent to allow your application to access aspects of their Amazon Music account data. It is recommended that the client does not include scopes unless absolutely necessary in order to accurately represent to customers what access permissions will be required.
Scopes are formatted as <service>::<category>:<read>. Scopes with the <read> suffix are read-only. Non-read scopes supersede read scopes. In other words, if the client has scope music::library (a scope which grants full access to an account's library) it does not need to also request music::library:read (a scope that grants read-only access).
3B. SCOPES TABLE
| Scope | Description |
|---|---|
| music::catalog | Search the Amazon music catalog |
| music::favorites | Read which users and artists a customer follows and update them on their behalf. |
| music::favorites:read | Read which users and artists a customer follows. |
| music::history | Read a customer's listening history |
| music::library | Read a customer's music library and update playlists on their behalf. |
| music::library:read | Read a customer's music library and playlists. |
| music::playback | Enable Amazon Music media playback and playback device discovery. |
| music::profile | Read a customer's music profile and update settings on their behalf. |
| music::profile:read | Read a customer's music profile and settings. |
| music::recommendation | Read Amazon Music recommendation's on a customer's behalf. |
4. Auth header parameters
Calls to the Amazon Music Web API must always include two header parameters: Authorization and x-api-key. The value of Authorization should be the bearer token you received from the LWA service. And the value of x-api-key should be your LWA Security Profile ID. The Security Profile ID is not the same as the Client ID you used to acquire the LWA token. You will find it in the general tab of the Security Profile Management page in the LWA Console the ID looks like amzn1.application.xxxxxxxxxx, which is different than the Client ID with is prefixed with amzn1.application-oa2-client.xxx
5. Token expiration
Bearer tokens expire after a certain amount of time, typically one hour. The expires_in parameter will specify when the token expires. The client should keep track of this and refresh the token before the expiration. If a token expires, API requests will return a 401 HTTP status error with the error code INVALID_ACCESS_TOKEN.
