Unauthenticated calls to the Spotify API are going away on the 29th of May. Clients of the API will have to transition to another method of authentication before the deadline in order to keep working as expected. A good walkthrough of how to do authentication is available in the announcement post. The features that each authentication flow provides are as follows:
| Requires Client Secret | Refreshable | User Login | |
|---|---|---|---|
| Client Credentials | ✓ | ✓ | ✗ |
| Implicit Grant | ✗ | ✗ | ✓ |
| Authorization Code | ✓ | ✓ | ✓ |
The Client Secret is a component of your Spotify Application Credentials. Along with the Client ID, it's used in two of the three OAuth flows to verify that the request is genuine. It's extremely important that your Client Secret remains secret. This means that it cannot be available to your client directly - it must be stored on your trusted server. If you suspect that your Client Secret has been compromised, you can regenerate it in your applications settings. If your Client Secret has been compromised, and an unauthorized party makes unusual or abusive requests to the API, your app may be flagged as malicious, and deactivated.
If your app does not require user login, you should use the Client Credentials flow to authenticate your requests, making sure to handle your Client Secret appropriately (i.e. on a server).
If your app requires user login, or if you do not want to deal with a server, you are ok with an unrefreshable token that expires 1 hour after login, and you don't mind requiring your users to log in to Spotify to enable the functionality, the Implicit Grant flow is for you.
Otherwise, if your app should only require users to log in once, and be able to refresh in perpetuity, the Authorization Code flow is for you.
If you've chosen the Client Credentials or Authorization Code flow, your authorization code may require a server component. If your code is only running on a trusted device (i.e. your own server), you could implement Client Credentials in your client code directly. If your app is to run on 3rd party untrusted devices (such as in end-user's browsers, on their phones, etc.), you'll need a server to keep your Client Secret secure.
This repository contains a Node.js implementation of a server to assist clients using the Client Credentials or Authorization Code flows, keeping the Client Secret on the server. Keep it secret, keep it safe!
Note: The tokens generated by this service can be used both in the Spotify API and in the Android and iOS SDKs as long as the correct scope (streaming for Music Streaming in the mobile SDKs).
This server can be run on any infrastructure that'll run Node.js - Google App engine, a VPS, Bare Metal, or even a Raspberry Pi (I'm guessing, this isn't tested).
Alternatively, you could use the Deploy to Heroku button and follow the wizard to get up and running quickly.
The app depends on a Redis instance and a Spotify Application. The application reads details about them from environmental variables. Specifically, the following environmental variables are required.
REDIS_URL= # The URL to your Redis instance
CLIENT_ID= # Your Spotify Client ID
CLIENT_SECRET= # Your Spotify Client Secret
You can deploy your Redis instance however you like. If you chose to follow the Heroku deployment method, the wizard will set this up for you. The REDIS_URL should be a connect URL to your Redis instance - make sure you've configured your Redis instance to accept connections from your server!
As for the Spotify Application Credentials - You can register these on the Spotify Developer Dashboard. Please see the Registering Your Application guide for more info. Once you've registered your application, if you wish to use the Authentication Code flow, you should add a Redirect URI on the settings page - it should look like $HOST/spotifyOauthCallback, where $HOST contains the server protocol and hostname to where you've deployed your server. This is to facilitate the redirect from the Spotify Accounts Service back to your instance of this server, which will in turn redirect the user back to your application. See the Authorization Code section for more information. If you don't intend to use the Authorization Code flow, don't add a redirect URI - this will disable the Authorization Code flow component of the server.
To get a client credentials access token, make a GET request to the /clientCredentials endpoint of this service.
| Query Parameters | Value |
|---|---|
| client_id | The client id of your Spotify Application. It must match the $CLIENT_ID environmental variable consumed by this server |
It will return an object matching the schema:
{
"access_token": "BQBpv...axnkA",
"token_type": "Bearer",
"expires_in": 3600
}You can use the returned access_token to make requests to the Spotify API. To refresh, just make the same request again - it will provide a new access token. Remember, the Client Credentials flow does not authorize any users, so you'll only be able to make requests to endpoints that don't require any scopes.
The Authorization Code flow is the most complex of the three flows offered by Spotify. It requires a Client Secret (therefore requiring a server side component), and involves a little co-ordination. This application abstracts most of the complexity away from your client.
To begin the Authorization Flow, you'll need to display the Spotify Authorization Dialog to your user. You can do this in a WebView, a Popup, or in the user's default browser - anything that acts as a web browser will work fine. Make sure your user's browser is configured follows redirects! Start by redirecting them to:
$HOST/login
with the following Query Parameters:
| Query Parameters | Value |
|---|---|
| client_id | The client id of your Spotify Application. It must match the $CLIENT_ID environmental variable consumed by this server |
| scope | A comma separated list of the Spotify Scopes you want to ask the user for permission under |
| redirect_uri | This is the URI that you want the user to be redirected to once the authorization flow is complete. An access token and a refresh token will be passed to your application in the fragment component of this URI, which you can parse and use in your application. |
Here's an example URI with the query parameters added.
https://your-spotify-oauth-server.example.com/login?client_id=f80005920181e5dc0e6&scope=user-read-recently-played&redirect_uri=your-app-uri-scheme%3A%2F%2FspotifyAuthorizationCallback
The server will redirect the user to the Spotify Accounts Service, asking them to grant permission to your app under the requested scopes.
If the user rejects your app's request, they will be redirected back to your app (via your instance of this authorization server), with error details in the fragment component of your redirect_uri.
If the user accepts your app's request, they will be redirected back to your app (via your instance of this authorization server), with a URLencoded list of values from the Spotify Accounts Service, importantly including an access_token, and a refresh_token.
An example URI that your user will be redirected to (corresponding to the above request) is as follows:
your-app-uri-scheme://spotifyAuthorizationCallback#access_token=BQA...MjB&token_type=Bearer&expires_in=3600&refresh_token=AQD...VfM&scope=user-read-recently-played
You can use the access token to make requests to the Spotify API or to instantiate a copy of the Spotify Android or iOS SDKs. You should store your refresh_token in your client for later use.
After 60 minutes of use, your access_token will expire, requiring you to refresh the token. To do this, you can make a GET request to the /refresh endpoint of your instance of this service.
GET $HOST/refresh
Which accepts the following Query Parameters:
| Query Parameters | Value |
|---|---|
| client_id | The client id of your Spotify Application. It must match the $CLIENT_ID environmental variable consumed by this server |
| refresh_token | The refresh_token that you saved when you handled the authorization redirect |
A call to this API with the correct client_id and a valid refresh_token will return a new access_token in a JSON object that looks like:
{
"access_token": "BQB...Ieo",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "user-read-recently-played"
}Remember to keep your refresh_token saved for later use. It's also worth noting that a user may revoke your app's refresh token by navigating to the Spotify Apps Settings page, in which case, the /refresh endpoint will return an error object. Your client should handle this case.
Congrats on implementing secure Spotify Accounts Authorization! Thanks for keeping your Client Secret safe! For more information about Spotify Platform's authentication and authorization offering, please see the Spotify Platform Authorization Guide. If you have any questions, please reach out to @SpotifyPlatform on Twitter.