Amazon Music

Authentication

Important: These Amazon Music APIs are currently in a closed Beta. To join the waitlist, select 'Music Developers' in the contact us form here.

Important: These Amazon Music documents are in preview status. Be aware that content may change. Please use the developer forum for any questions or comments.

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.

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.

Application-specific guidelines

Login With Amazon offers a number of login methods for the end user. The choice of which to use will depend on the specific requirements of your device.

Devices with web browsers should use the web-based login. Click here to learn more about LWA for websites.
Devices without web browsers such as TVs can use a special code-based login. Click here to learn more about LWA for TVs.
Devices running Android can use the Android-based login. Click here to learn about LWA for Android devices.
Devices running iOS can use the iOS-based login. Click here to learn about LWA for iOS devices.

Calling LWA for use with Amazon Music

The LWA documentation above will guide you through the authorization process that applies to your specific application. The Amazon Music-specific component of this process is scope. Scopes allow access to user accounts in a controlled, limited way. In some cases, a scope request may prompt the user for their consent in allowing an application to access certain account data or granting the application permissions.

When you make a device authorization request to LWA you must specify a scope. You can request more than one scope at once: simply separate scopes with spaces. Which scope(s) you need depends on the API functionality you will need access to. APIs will specify required scopes within their individual documentation.

The Security Profile 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).

SCOPES

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.

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

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.

Further information

The complete Login With Amazon documentation can be found here.