This guide shows you how to get a user’s authorization to access private data through the Web API.

Introduction

Some requests to the Spotify Web API require authorization; that is, the user must have granted permission for an application to access the requested data. To prove that the user has granted permission, the request header sent by the application must include a valid access token.

As the first step towards authorization, you will need to register your application. That will give you a unique client ID and client secret key to use in the authorization flows.

Supported Authorization Flows

The Spotify Web API currently supports three authorization flows:

  • The Authorization Code flow first gets a code then exchanges it for an access token and a refresh token. Since the exchange uses your client secret key, you should make that request server-side to keep the integrity of the key. An advantage of this flow is that you can use refresh tokens to extend the validity of the access token.
  • The Client Credentials flow allows you to get an access token by supplying your client credentials (client ID and secret key). This flow is used in server-to-server authentication. Only endpoints that do not access user information can be accessed. Its advantage is that a higher rate limit is applied compared with requests to the Web API made without an access token.
  • The Implicit Grant flow is carried out client-side and does not involve secret keys. The access tokens that are issued are short-lived and there are no refresh tokens to extend them when they expire.
FlowCan fetch a user’s data by requesting access?
Uses secret key? (key exchange must happen server-side!)
Access token can be refreshed?Improved rate limits?
Authorization Code
Yes
Yes
YesYes
Client Credentials
No
Yes
NoYes
Implicit Grant
Yes
No
NoYes
UnauthorizedNoNoNoNo
Additional Help: You can read our step-by-step tutorial where we explain how to run an example application using these flows. In addition, we have a list of handy wrappers and tools for your language of choice.

Authorization Code Flow

This method is suitable for long-running applications which the user logs into once. It provides an access token that can be refreshed. Since the token exchange involves sending your secret key, this should happen on a secure location, like a backend service, not from a client like a browser or mobile apps. This flow is described in RFC-6749. This flow is also the authorization flow used in our Web API Tutorial.

Authorization Code Flow Diagram

1. Your application requests authorization

The authorization process starts with your application sending a request to the Spotify Accounts service. (The reason your application sends this request can vary: it may be a step in the initialization of your application or in response to some user action, like a button click.) The request is sent to the /authorize endpoint of the Accounts service:

GET https://accounts.spotify.com/authorize

The request will include parameters in the query string:

Query parameter
Value
client_id
Required. The client ID provided to you by Spotify when you register your application.
response_type
Required. Set it to code.
redirect_uri
Required. The URI to redirect to after the user grants/denies permission. This URI needs to have been entered in the Redirect URI whitelist that you specified when you registered your application. The value of redirect_uri here must exactly match one of the values you entered when you registered your application, including upper/lowercase, terminating slashes, etc.
state
Optional, but strongly recommended. The state can be useful for correlating requests and responses. Because your redirect_uri can be guessed, using a state value can increase your assurance that an incoming connection is the result of an authentication request. If you generate a random string or encode the hash of some client state (e.g., a cookie) in this state variable, you can validate the response to additionally ensure that the request and response originated in the same browser. This provides protection against attacks such as cross-site request forgery. See RFC-6749.
scope
Optional. A space-separated list of scopes: see Using Scopes. If no scopes are specified, authorization will be granted only to access publicly available information: that is, only information normally visible in the Spotify desktop, web and mobile players.
show_dialogOptional. Whether or not to force the user to approve the app again if they’ve already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If true, the user will not be automatically redirected and will have to approve the app again.

A typical request looks like this:

GET https://accounts.spotify.com/authorize/?client_id=5fe01282e44241328a84e7c5cc169165&response_type=code&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=user-read-private%20user-read-email&state=34fFs29kd09

2. The user is asked to authorize access within the scopes

The Spotify Accounts service presents details of the scopes for which access is being sought. If the user is not logged in, they are prompted to do so using their Spotify credentials.

When the user is logged in, they are asked to authorize access to the data sets defined in the scopes.

3. The user is redirected back to your specified URI

After the user accepts (or denies) your request, the Spotify Accounts service redirects back to the redirect_uri. For our example, this would be the address:

https://example.com/callback

If the user has accepted your request, the response query string contains the following parameters:

Query parameter
Value
code
An authorization code that can be exchanged for an access token.
state
The value of the state parameter supplied in the request.

For example:

https://example.com/callback?code=NApCCg..BkWtQ&state=profile%2Factivity

If the user has not accepted your request or an error has occurred, the response query string contains the following parameters:

Query parameter
Value
error
The reason authorization failed, for example: “access_denied”
state
The value of the state parameter supplied in the request.

For example:

https://example.com/callback?error=access_denied&state=STATE

4. Your application requests refresh and access tokens

When the authorization code has been received, you will need to exchange it with an access token by making a POST request to the Spotify Accounts service, this time to its /api/token endpoint:

POST https://accounts.spotify.com/api/token

The body of this POST request must contain the following parameters:

Request body parameter
Value
grant_type
Required. As defined in the OAuth 2.0 specification, this field must contain the value "authorization_code".
code
Required. The authorization code returned from the initial request to the Account's /authorize endpoint.
redirect_uri
Required. This parameter is used for validation only (there is no actual redirection). The value of this parameter must exactly match the value of redirect_uri supplied when requesting the authorization code.
Header parameter
Value
Authorization
Required. Base 64 encoded string that contains the client ID and client secret key. The field must have the format: Authorization: Basic <base64 encoded client_id:client_secret>

An alternative way of sending the client id and secret is as request parameters (client_id and client_secret) in the POST body, instead of sending them base64-encoded in the header.

5. The tokens are returned to your application

On success, the response from the Spotify Accounts service has the status code 200 OK in the response header, and the following JSON data in the response body:

Key
Value typeValue description
access_token
stringAn access token that can be provided in subsequent calls, for example to Spotify Web API services.
token_type
stringHow the access token may be used: always "Bearer".
expires_in
intThe time period (in seconds) for which the access token is valid.
refresh_token
stringA token that can be sent to the Spotify Accounts service in place of an authorization code. (When the access code expires, send a POST request to the Accounts service /api/token endpoint, but use this code in place of an authorization code. A new access token will be returned. A new refresh token might be returned too.)

An example cURL request and response from the token endpoint will look something like this:

curl -H "Authorization: Basic ZjM...zE=" -d grant_type=authorization_code -d code=MQCbtKe...44KN -d redirect_uri=https%3A%2F%2Fwww.foo.com%2Fauth https://accounts.spotify.com/api/token
{
   "access_token": "NgCXRK...MzYjw",
   "token_type": "Bearer",
   "expires_in": 3600,
   "refresh_token": "NgAagA...Um_SHo"
}

6. Use the access token to access the Spotify Web API

The access token allows you to make requests to the Spotify Web API on a behalf of a user, for example:

curl -H "Authorization: Bearer NgCXRK...MzYjw" https://api.spotify.com/v1/me
{
  "display_name":"JMWizzler",
  "email":"email@example.com",
  "external_urls":{
    "spotify":"https://open.spotify.com/user/wizzler"
  },
  "href":"https://api.spotify.com/v1/users/wizzler",
  "id":"wizzler",
  "images":[{
    "height":null,
    "url":"https://fbcdn...2330_n.jpg",
    "width":null
  }],
  "product":"premium",
  "type":"user",
  "uri":"spotify:user:wizzler"
}

7. Requesting access token from refresh token

Access tokens are deliberately set to expire after a short time, after which new tokens may be granted by supplying the refresh token originally obtained during the authorization code exchange.

The request is sent to the token endpoint of the Spotify Accounts service:

POST https://accounts.spotify.com/api/token

The body of this POST request must contain the following parameters:

Request body parameterValue
grant_type
Required. Set it to “refresh_token”.
refresh_token
Required. The refresh token returned from the authorization code exchange.

The header of this POST request must contain the following parameter:

Header parameter
Value
Authorization
Required. Base 64 encoded string that contains the client ID and client secret key. The field must have the format: Authorization: Basic <base64 encoded client_id:client_secret>

For example:

curl -H "Authorization: Basic ZjM4Zj...Y0MzE=" -d grant_type=refresh_token -d refresh_token=NgAagA...NUm_SHo https://accounts.spotify.com/api/token
{
   "access_token": "NgA6ZcYI...ixn8bUQ",
   "token_type": "Bearer",
   "expires_in": 3600
}

Client Credentials Flow

The method makes it possible to authenticate your requests to the Spotify Web API and to obtain a higher rate limit than you would get without authentication. Note, however that this flow does not include authorization and therefore cannot be used to access or manage a user’s private data. This flow is described in RFC-6749.

Client Credentials Flow Diagram

1. Your application requests authorization

The request is sent to the /api/token endpoint of the Accounts service:

POST https://accounts.spotify.com/api/token

The request will include parameters in the request body:

Request body parameter
Value
grant_type
Required. Set it to “client_credentials”.

The header of this POST request must contain the following parameter:

Header parameter
Value
Authorization
Required. Base 64 encoded string that contains the client ID and client secret key. The field must have the format: Authorization: Basic <base64 encoded client_id:client_secret>

For example:

curl -H "Authorization: Basic ZjM4ZjAw...WY0MzE=" -d grant_type=client_credentials https://accounts.spotify.com/api/token
{
   "access_token": "NgCXRKc...MzYjw",
   "token_type": "bearer",
   "expires_in": 3600,
}

2. Use the access token to access the Spotify Web API

The access token allows you to make requests to the Spotify Web API endpoints that do not require user authorization such as the Get a track endpoint, for example:

curl -H "Authorization: Bearer NgCXRKc...MzYjw" https://api.spotify.com/v1/tracks/2TpxZ7JUBn3uw46aR7qd6V
{
  "album" : {
    "album_type" : "album",
    "external_urls" : {
      "spotify" : "https://open.spotify.com/album/6akEvsycLGftJxYudPjmqK"
    },
    "href" : "https://api.spotify.com/v1/albums/6akEvsycLGftJxYudPjmqK",
    "id" : "6akEvsycLGftJxYudPjmqK",
    "images" : [ {
      "height" : 640,
      "url" : "https://d3rt1990lpmkn.cloudfront.net/original/f2798ddab0c7b76dc2d270b65c4f67ddef7f6718",
      "width" : 640
    }, {
...

Implicit Grant Flow

Implicit grant flow is for clients that are implemented entirely using JavaScript and running in the resource owner’s browser. You do not need any server-side code to use it. Rate limits for requests are improved but there is no refresh token provided. This flow is described in RFC-6749.

Implicit Grant Flow Diagram

1. Your application requests authorization

Redirect the user to the /authorize endpoint of the Accounts service:

GET https://accounts.spotify.com/authorize

The request will include parameters in the query string:

Query parameter
Value
client_id
Required. The client ID provided to you by Spotify when you register your application.
response_type
Required. Set it to “token”.
redirect_uri
Required. The URI to redirect to after the user grants/denies permission. This URI needs to be entered in the URI whitelist that you specify when you register your application.
state
Optional, but strongly recommended. The state can be useful for correlating requests and responses. Because your redirect_uri can be guessed, using a state value can increase your assurance that an incoming connection is the result of an authentication request. If you generate a random string or encode the hash of some client state (e.g., a cookie) in this state variable, you can validate the response to additionally ensure that the request and response originated in the same browser. This provides protection against attacks such as cross-site request forgery. See RFC-6749.
scope
Optional. A space-separated list of scopes: see Using Scopes.
show_dialogOptional. Whether or not to force the user to approve the app again if they’ve already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If true, the user will not be automatically redirected and will have to approve the app again.

For example you would redirect the user to

https://accounts.spotify.com/authorize?client_id=5fe01282e94241328a84e7c5cc169164&redirect_uri=http:%2F%2Fexample.com%2Fcallback&scope=user-read-private%20user-read-email&response_type=token&state=123

2. The user is asked to authorize access within the scopes

The Spotify Accounts service presents details of the scopes for which access is being sought. If the user is not logged in, they are prompted to do so using their Spotify username and password.

When the user is logged in, they are asked to authorize access to the data sets defined in the scopes.

3. The user is redirected back to your specified URI

After the user grants (or denies) access, the Spotify Accounts service redirects the user to the redirect_uri. For our example, this would be the address:

https://example.com/callback

If the user has granted access, the final URL will contain a hash fragment with the following data encoded as a query string:

Query parameter
Value
access_token
An access token that can be provided in subsequent calls, for example to Spotify Web API services.
token_type
Value: “Bearer”
expires_in
The time period (in seconds) for which the access token is valid.
state
The value of the state parameter supplied in the request.

For example:

https://example.com/callback#access_token=NwAExz...BV3O2Tk&token_type=Bearer&expires_in=3600&state=123

If the user has denied access, there will be no access token and the final URL will have a query string containing the following parameters:

Query parameter
Value
error
The reason authorization failed, for example: “access_denied”
state
The value of the state parameter supplied in the request.

For example:

https://example.com/callback?error=access_denied&state=123

4. Use the access token to access the Spotify Web API

The access token allows you to make requests to the Spotify Web API. For example, if you are using jQuery, you would do:

$.ajax({
   url: 'https://api.spotify.com/v1/me',
   headers: {
       'Authorization': 'Bearer ' + accessToken
   },
   success: function(response) {
       ...
   }
});

Scopes

Scopes let you specify exactly what type of data access your application needs. Check the “Required Scope” column, if any, in the description of the object you are trying to retrieve to assess the needed scopes. For more information, see Using Scopes.

The generated access token will contain permissions for the scopes that the user has already granted for that client_id, if any.

When not specifying any scopes the access token will allow access to certain publicly available information by default. You can find out more information on Using Scopes.

Frequently Asked Questions about Authorization

Accessing your data without showing a login form

I want to interact with the web API and show some data on my website. I see that the endpoints I need authorization, but I don’t need/want a login window to pop-up, because I want to grant my own app access to my own playlists once. Is there any way of doing this?

You basically need an access token and a refresh token issued for your user account. For obtaining a pair of access token / refresh token you need to follow the Authorization Code Flow (if you need a certain scope to be approved) or Client Credentials (if you just need to sign your request, like when fetching a certain playlist). Once you obtain them, you can use your access token and refresh it when it expires without having to show any login form.

I want to create a quick script to add a new song every day to my playlist. Is there a way I can do this without having to open the browser and log in every day? I could set my user and password in the script.

The Spotify Web API doesn’t support authorization through username/password. For this use case you would obtain an access token through the Authorization code. See the response above.

Is there any way to override the HTTP verb? E.g. sending a method=delete query parameter in a GET request.

The Web API doesn’t support method override at the moment. If you want to consume the API from IE9 and below using XDomainRequest, which does not support custom headers, you will need to proxy those requests or make them server-side.