Client Side Applications

The Beats Music API supports the OAuth 2.0 protocol in JavaScript-based applications. These applications may access a Beats Music API while the user is present at the application, and cannot keep a secret.

As the client application, which is typically JavaScript running in a browser is less trusted, no refresh tokens for long lived access are returned. You should use this flow for client-side applications (JavaScript) that need temporary access (a few hours) to a users data.

This tutorial assumes you have already registered your application, and helps you integrate the Beats Music OAuth 2.0 flow into your JavaScript application.

Overview

Begin by redirecting a browser to a Beats Music URL with a set of query parameters that indicate the type of Beats Music access the application requires. Beats Music returns the access token with the response from which the client-side script extracts that access token.

The application may access a Beats Music API after it receives the access token. Your application should always use HTTPS in this scenario.

The Relevant Beats Music endpoints are:

https://partner.api.beatsmusic.com/v1/oauth2/authorize

Scope:

The scope of an access token using the implicit flow is limited to read only since client side applications cannot keep a secret. You'll need to request the authorization grant flow via the Web Server Authentication for write permissions, such as updating a playlist.

Implementing the Flow

Forming the URL

To retrieve the access token for a user, form a URL with the https://partner.api.beatsmusic.com/v1/oauth2/authorize endpoint  using these query parameters, which are described in the table below. 

https://partner.api.beatsmusic.com/v1/oauth2/authorize?
    state=[OPTIONAL STATE]
    &response_type=token
    &redirect_uri=[YOUR_REDIRECT_URL]
    &client_id=[YOUR_CLIENT_ID]

For client applications, specify token as the response type. For example:

https://partner.api.beatsmusic.com/v1/oauth2/authorize?state=xyz
    &response_type=token
    &redirect_uri=http%3A%2F%2Fwww.example.com
    &client_id=nnn

The browser will prompt you to connect the application with your Beats Music Account:

After you enter the credentials for your Beats Music account, the browser redirects to the following URL, which contains the access token (access_token=bcwesw5h6v7ed5kcz9nq2643 in this example):

http://www.example.com/cb?
    scope=umMa
    &access_token=bcwesw5h6v7ed5kcz9nq2643
    &token_type=bearer
    &expires_in=3600
    &state=xyz

NOTE: The authorize endpoint is accessible over SSL, and insecure HTTP connections are refused.

Parameters

The Beats Music authorize endpoint supports the following set of query string parameters for client-side applications:

Handling the Response

Beats Music returns an access token to your application, provided the user grants your application the requested permissions. The access token is returned to your application in the query string. Other parameters in the response include indicate the lifetime of the token in seconds (expires_in), and the kind of token that is being returned (token_type). If the state parameter was included in the request, then it is also included in the response.

Successful access token response:

HTTP/1.1 302 Found
Location: http://www.example.com/cb?
    scope=uUmMa
    &access_token=zteb94tbe7rncnf8mkxgw527
    &token_type=bearer
    &expires_in=3600
    &state=xyz

Error response:

HTTP/1.1 302 Found
Location: http://www.example.com/cb?error=access_denied

You're done! You can now use the access token in your Beats Music API requests.

curl -X GET "https://partner.api.beatsmusic.com/v1/api/tracks/tr51760477/audio?
&access_token=bcwesw5h6v7ed5kcz9nq2643"