This tutorial shows you how to create a small server-side application that accesses user-related data through the Spotify Web API.

By using the Spotify Tools, you accept our Developer Terms of Use.

About This Tutorial

Through the Spotify Web API, external applications can retrieve Spotify content such as album data and playlists. If an application wants to access user-related data through the Web API, it must get the user’s authorization to access that data.

This tutorial is based around the creation of a simple application using Node.js and JavaScript. We will show you how to:

  • Register an application with Spotify,
  • Authenticate a user,
  • Get authorization to access the user’s data,
  • Retrieve that data from a Web API endpoint.

The authorization flow we will use in this tutorial is the Authorization Code Flow. This flow first gets a code from the Spotify Accounts Service, then exchanges that code for an access token. The code-to-token exchange requires a secret key, and for security is done through direct server-to-server communication.

The data that we will retrieve will be from the Web API’s /me endpoint, and will include information about the current user.

The complete source code of the app that we will create in this tutorial is available on GitHub.

Setting Up Your Account

To be able to use the Web API, the first thing you will need is a Spotify user account (Premium or Free). To get one, simply sign up at

When you have a user account, go to the My Applications page at the Spotify Developer website and, if necessary, log in. Accept the latest Developer Terms of Use to complete the set-up of your account.

Registering Your Application

Any application can request data from Spotify Web API endpoints and many endpoints are open and will return data without requiring registration. However, if your application seeks access to a user’s personal data (profile, playlists, etc.) it must be registered. Registered applications also get other benefits, like higher rate limits at some endpoints.

You can register your application, even before you have created it. Follow these steps to register an application:

  1. Go to the My Applications page at the Developer website.
  2. Click Create a new application.
  3. Enter the name of your application (for example, “My Test Application”.) Note that this name will be shown in the pop-up that asks the user for authorization to access their Spotify data (see Running the Application, below).
  4. Enter an application description.
  5. Click Create. The application details screen will open:myapp-details-screen
  1. Enter the address of a Website where the user can find more information about your application (for example, its user guide, terms of use, licensing restrictions, and support information).
  2. Add any Redirect URIs that the Spotify Accounts service could call when authentication process completes. You can enter multiple addresses, for example, one for authentication on mobile devices, one for desktop machines.
    Important: When you call the Spotify Accounts service from your application, you will send a redirect-uri in the call. The redirect-uri is the address that the Spotify Accounts service redirects to after authorization succeeds or fails. If you do not white-list that URI here, authorization will fail. Any URI you enter here must exactly match the value you later use in the calls to the Accounts Service, including upper/lowercase characters, terminating slashes, and so on.
    Note: If your redirect_uri points to a directory, include a trailing slash (/)—otherwise some browsers may have a problem handling the redirect. You do not need to add a trailing slash to your URI if it points to a file. You should also check that your server does not add or remove trailing slashes when handling the incoming redirect URI as that can also cause problems.

    For the purposes of this tutorial, add this URI to the Redirect URIs whitelist:

  3. Click Save to complete the registration of your application.
  4. Your application will now be shown, along with any other applications you have registered, in the main list on the My Applications page:

Getting the Client ID and Secret Key

When you register an application on your account, two credentials are created for you. You will need them to make calls from your application to the Spotify web services. You can see the credentials on the application’s details page:

  • Client ID—the unique identifier for your application. It does not need to be stored securely and usually it does not need to be changed. (If for some reason you do need to change the client ID, you will need to delete your application from your account and register it again.)
  • Client Secret—the key that you will need to pass in secure calls to the Spotify Accounts and Web API services.
    Always store the client secret key securely; never reveal it publicly! If you suspect that the secret key has been compromised, regenerate it immediately by clicking the link on the application details page.

Preparing Your Environment

Now that you have registered our application, we need to set up your environment. We’ll describe how to do that now.

(If you are already confident of your setup, you might want to skip ahead and just download the code of our Authentication Flow example app from GitHub.)

Because we are creating a server-side application in this tutorial, we will need the help of an appropriate software platform. For this, we will use Node.js (version 0.10.25). If you do not already have Node.js, download it and install it with the default settings for your environment.

Now test that Node.js is installed and set up correctly: in your favourite text editor create a simple server.js file with the following code:

/* Load the HTTP library */
var http = require("http");

/* Create an HTTP server to handle responses */
http.createServer(function(request, response) {
  response.writeHead(200, {"Content-Type": "text/plain"});
  response.write("Hello World");

This code creates a simple HTTP server on your local machine. Save the file in a folder named njtest and then execute the file in the command prompt:

cd njtest
node server.js

Now open a browser and go to the URL localhost:8888. You should see the words “Hello World” in your browser window:


Kill the server by typing CTRL-C in the command prompt window.

We have now completed and checked our set up of Node.js. If you cannot get the example above to work, troubleshoot and fix it before continuing.

Note: In our endpoint reference pages we show cURL syntax for our example requests. You do not need cURL to complete this tutorial, but you will probably find it a helpful tool when developing your application; it will help you formulate requests to Spotify web services and see the responses the return. Install the version with SSL support it if you need it.

Creating the Project Folder and Files

Now that you have installed Node.js, make a project folder for your application and download or clone into it our OAuth examples from our GitHub repository.

The code of the OAuth examples depends on the packages express,request and querystring. Install the dependencies running the following command (make sure you do this within the folder you just created!):

npm install

When the installation is completed, check that your project folder now contains a subfolder called node_modules, and that that folder contains at least those packages.

Prompting the User to Login

Let’s examine the code of the Authorization Code example.

Open the authorization_code folder:

cd authorization_code

The folder called public is our web root — it is where we have put the public web pages for our application. (Note that all other files are located outside of this folder and are therefore not accessible to the application user.)

Open the file index.html. This file provides a simple interface that prompts the user to login:

  <style type="text/css">
  #login {
    display: none;

  #loggedin {
    display: none;
    <div id="login">
     <h1>First, log in to spotify</h1>
     <a href="/login">Log in</a>
    <div id="loggedin">

 <script id="loggedin-template" type="text/x-handlebars-template">
    <h1>Logged in as {{display_name}}</h1>
    <img id="avatar" width="200" src="{{images.0.url}}" />
     <dt>Display name</dt><dd>{{display_name}}</dd>
     <dt>Spotify URI</dt><dd><a href="{{external_urls.spotify}}">{{external_urls.spotify}}</a></dd>
     <dt>Link</dt><dd><a href="{{href}}">{{href}}</a></dd>
     <dt>Profile Image</dt><dd>{{images.0.url}}</dd>
    <p><a href="/">Log in again</a></p>

This HTML file actually serves a dual function in our application: as well as providing a “Log in” link and making the call to the Web API (not shown in the listing above) and provides a template for displaying the data that will be returned by the Web API’s /me endpoint.

Providing the Application Credentials

The file called app.js contains the main code of our application. Open it in an editor and you will find that it contains code for:

  • Creating a server on your local machine,
  • Handling the user’s login request,
  • Specifying the scopes for which authorization is sought,
  • Performing the exchange of the authorization code for an access token,
  • Calling the Web API endpoint.

There are some lines of code in this file containing the client ID, secret key and redirect URI:

var client_id = 'CLIENT_ID'; // Your client id
var client_secret = 'CLIENT_SECRET'; // Your secret
var redirect_uri = 'REDIRECT_URI'; // Your redirect uri

They contain sample values, so if you want to try the app out we recommend that you replace them with the values that you were given when you registered your app. This guide will suppose we are using http://localhost:8888/callback as the redirect URI.

You can also see in this file the data scopes that we are going to ask the user for authorization to access:

var scopes = 'user-read-private user-read-email'

That means that the app will be requesting access to the user’s full name, profile image, and email address.

Calling the Spotify Accounts Service

You will see that the app.js file contains three calls to the Spotify Accounts Service. The first call is the service’s /authorize endpoint, passing to it the client ID, scopes, and redirect URI. This is the call that starts the process of authenticating to user and gets the user’s authorization to access data.

The second call is to the Spotify Accounts Service’s /api/token endpoint, passing to it the authorization code returned by the first call and the client secret key. This second call returns an access token and also a refresh token.

Note that, as app.js is not in our /public directory, its machinations cannot be seen from a web browser. This is important because we never want to expose our application’s secret key to a user. Make sure that you safeguard your application’s secret key at all times. Be aware, for example, that if you commit your code to a public repository like GitHub you will need to remove the secret key from your code before doing so.

For a better understanding of the Accounts Service’s endpoints and the parameters passed in each call, see the full description of the Authorization Code Flow in our Web API Authorization Guide.

After both calls have been completed (and the user has authorized access), the application will have the access_token it needs to retrieve the user data from the Web API.

The third call, in the code managing requests to /refresh_token, a refresh token is sent to /api/token. This will generate a new access token that we can issue when the previous has expired.

Running the Application

Start the server by running the following command at the command prompt:

node app.js

Open a browser and visit the project’s home page again. Now that we have our server running, you can use the following URL:


If you visit the file in a browser (http://localhost:8888) you should see the initial display:


Click the “Log in” link. The Spotify Accounts login window will appear:


Log in with your Spotify credentials. You will now be taken to the authorization screen where permission is requested to access your account data:


The Spotify Accounts Service will now use the redirect_uri to return to the application, passing back the authorization_code which is subsequently exchanged in a second call for an access_token.

Now our home page can make its call to the Web API endpoint at /me and retrieve data, and render it:


If you click on “Obtain new token using the refresh token” you will see that a new access token is generated.

This tutorial is now complete. Our example app does just enough to demonstrate how to get data using an authorization flow, but perhaps it can serve as a useful template for creating your own applications. Good luck!