HAQM Music
Authentication
OAuth 2.0 Protocol
The HAQM Music Web Service API uses Login With HAQM (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.
Login With HAQM
Login with HAQM (LWA) provides the authorization server for the HAQM Music API. LWA is a separate service from the core HAQM Music Service, and so its API may have different formats, structure, and requirements from the HAQM Music API documented here.
To use LWA, your business first needs to create an HAQM developer account, then create a Security Profile ID. Click here to learn how to create a Login With HAQM account.
To learn how to use Login With HAQM to request an authentication token, click here.
Application-specific guidelines
Login With HAQM 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 HAQM Music
The LWA documentation above will guide you through the authorization process that applies to your specific application. The HAQM 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 HAQM 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 HAQM Music contact.
When logging in, users will be prompted for consent to allow your application to access aspects of their HAQM 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 HAQM 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 HAQM 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 HAQM Music recommendation's on a customer's behalf. |
Auth header parameters
Calls to the HAQM 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 HAQM documentation can be found here.