Licensor Playbook

@stseng

Web API

Music

Product

Strategy

2023

Proprietary & Confidential

Spotify

Intro

2023

Proprietary & Confidential

Spotify

2023

Proprietary & Confidential

Spotify

Also known as the Open/Source API, the product is free for everyone to access. Implemented at the tailend of 2021, multiple product safeguards now help minimize unethical and forbidden use.

​

As a valued partner, you have a direct line of support, label-dev-support@spotify.com.

Web API as a Licensor Tool

2023

Proprietary & Confidential

Spotify

In simple terms

The Web API can be used to integrate apps, websites, platforms and internal tools with Spotify.

At the base level, this works using “requests” and “responses”

Capabilities include metadata extraction, user library management, playlist control, and audio playback control

Data is only accessible for content already released on platform

2023

Proprietary & Confidential

Spotify

Client ID

Unique App identification number. Multiple client IDs are allowed under one developer account. The same client ID may be used for different campaigns as long as it’s the same use case. Each Client ID has individually assigned rate limits.

​

Rate Limit

Max number of API calls/requests allowed within a period of time

​

Endpoint

Digital location that stores resources the client-side can request to access.

​

Quota Extension

Request through the developer account to transition new app from developer mode (max 25 users) to Extended Quota Mode, by assigning a proper rate limit after reviewing their submitted use case.

​

Scope Extension

Request to access additional scopes (permissions granted to the application). Available in Extended Quota Mode.

Useful Definitions

2023

Proprietary & Confidential

Spotify

Direct monetization through user attendance and any commercialization of user data

​

Experiences that could incentivize artificial streaming (e.g. trivia quizzes, games, stream for prize at the end)

​

Visual or voice elements overlapped with Spotify content or augmenting music directly

​

Integrations with streams/content from other DSPs

​

Displaying of Spotify content without proper attribution and linking to Spotify

​

Selling metadata, cover art or audio clips (e.g. NFTs, recreating the Spotify UX within your own app)

​

No clear opt in/opt out mechanism and explicit messaging during user authorization

​

​

​

​

TLDR:

Developer Policy

RED FLAGS

2023

Proprietary & Confidential

Spotify

Operational

Best Practices

​

2023

Proprietary & Confidential

Spotify

2023

Proprietary & Confidential

Spotify

First, check that you are logged out of your personal Spotify account. You can then create a developer account to access the developer portal.

• Pro-tip: Sign up using a domain alias (e.g. release-activations@spotify.com), for better organization, scalability, and to prevent disruption to your workflow if an employee is no longer with the company.

Once your account is set up, you can “create a new app” to generate your Client ID and Client Key.

• All new apps default on developer mode, which allows up to 25 users to test.
• Request a quota extension within the app module (Settings > Extension Requests) for a production-ready rate limit.
• Request a scope extension if you need additional API permissions.

Getting Started

2023

Proprietary & Confidential

Spotify

If you have Client IDs under personal email addresses, we can migrate them to a different developer account.

1. Create a developer account with the new email address
2. Create a new app within this new developer account
3. Send email and all the Client IDs you’d like to migrate, to your Commercial Label Partnerships Manager
4. They will confirm once the migration is complete

Centralizing Client IDs under a single developer account makes it easier for the designated team to monitor and manage correspondence from our API review team.

Consolidating Your Client IDs

SUBTITLE

2023

Proprietary & Confidential

Spotify

There will be times you will need to increase your rate limit to accommodate higher traffic, despite already being in “extended quota mode”. When this is necessary, please provide your Commercial Label Partnerships Manager with the following:

• Your Client ID
• One line of your use case (if any additions have been made since you were initially granted the extension)
• Estimated peak requests per minute or per second
• Estimated number of users
• Deadline

​

Asking for a higher rate limit

SUBTITLE

2023

Proprietary & Confidential

Spotify

Developer

Best Practices

​

2023

Proprietary & Confidential

Spotify

2023

Proprietary & Confidential

Spotify

Cache the ETag value alongside your cashed resource to make your API requests more efficient. When making a future API request to Spotify for the same content you can include an If-None-Match header with the value set to the cached ETag. Spotify will respond quickly with an 304 Not Modified status code if the resource hasn’t changed, and you can safely continue using your cached version of the resource.

Use Caching, ETags and If-None-Match

Many Web API resources include Entity Tags in the header. The ETag will change when the resource that you are requesting has changed.

2023

Proprietary & Confidential

Spotify

Spotify has four OAuth flows:

1. Client Credentials flow - A good choice for server-side apps that do not need to call any endpoints associated with a Spotify user’s personal account
2. Authorization Code flow - Popular option for server side apps that do authenticate Spotify users
3. Authorization Code flow with PKCE - Best for client side applications like iOS or Android apps where it would not be safe to store a client secret
4. Implicit Grant flow - Don’t use in any new apps. Use Authorization Code flow with PKCE instead.

Pick the right OAuth flow for your app

2023

Proprietary & Confidential

Spotify

Use OAuth scopes sparingly

When a Spotify user installs your app for the first time they will see a list of the OAuth scopes — or permission sets — that your app is requesting.

It is best to request as few scopes from the user as you possibly can. Users may be more wary of installing a third-party app that requests a lot of scopes or scopes that are more powerful.

In many cases you can avoid using Web API scopes by relying on built-in Spotify functionality. If the content is already available on the Spotify platform, instead of building a “save album to library” button in your app, consider linking the album’s open.spotify.com page so users can open the localized version in the album on their Spotify app and save the album in a UX they already know.

2023

Proprietary & Confidential

Spotify

Keep track of your app’s requests to Web API

In the Developer Dashboard you can find graphs displaying aggregated statistics on your app’s requests to the Web API. You can use those graphs to understand which API endpoints your app calls the most and to learn about major anomalies in API traffic.

You may also find it useful to implement logging on your own side to track calls that your app makes to the API and any errors that result from them. The logs can be used to identify opportunities to reduce the API calls that you make, and to report API problems to Spotify.

2023

Proprietary & Confidential

Spotify

Use the ‘Get Several’ APIs to fetch sets of data

Spotify has some APIs that third-party apps can use to read a batch of data in one go. For example, you can pass up to 50 artist IDs to the Get Several Artists API and get back information about many musicians in one API response. This can be a good way to make fewer network requests to Spotify, build faster applications, and protect your budget of API calls.

Bear in mind that it may take longer to render a response from these APIs than it would a response from other Spotify APIs with a smaller payload. Consider using the ‘Get Several’ endpoints for background API requests that don’t immediately block the user from completing a task or enjoying part of your app.

2023

Proprietary & Confidential

Spotify

Reusing Authorization Tokens

Reusing user Auth tokens can be useful when the app is performing the same function for returning users e.g. users don’t need to log in every time they want to pre-save upcoming tracks from their favorite artist. We permit reuse under the following circumstances:

1

2

3

Clear opt-in/opt-out and data deletion mechanism

​

If a user logs-out, User Data should be deleted unless necessary for providing functionality when the user is logged out (e.g IFTTT) or facilitating login.

​

If a user becomes inactive for more than 90 days, the developer should either delete User Data, or obtain the user’s consent to keep/refresh the data.

​

2023

Proprietary & Confidential

Spotify

Ad-Hoc

Best Practices

​

2023

Proprietary & Confidential

Spotify

2023

Proprietary & Confidential

Spotify

Novel Use Cases

​

Finding innovative ways to use the Web API is always encouraged. It may require troubleshooting or extra discussions around the developer policy so we highly recommend:

• Sharing your ideas with your Commercial Label Partnerships Manager so the Web API team can assess your use case prior to building everything
• Submitting your quota extension request early (1-2 weeks if possible) and provide as much context as possible
• Testing your app/website in production at least 72 hours in advance so Spotify is able to provide host-side tech support

2023

Proprietary & Confidential

Spotify

Technical Issues

​

If you run into issues with the integration, please share the following information with your Commercial Label Partnerships Manager

• Your application Client ID
• Which OAuth flow you are using (implicit grant, client credentials, or pixie flow)
• The scopes you have requested
• Error logs (response status codes), screenshots, test/live links, and other valuable context
• Your source code

2023

Proprietary & Confidential

Spotify

Additional Resources

The Web API only supplies metadata for content already published on-platform. If inquiries in adjacent areas arise, you can reach out to the following contacts:

• analytics-api@spotify.com for questions regarding your catalog’s performance metrics
• content-ops+ingestion@spotify.com for questions regarding the content ingestion and delivery pipeline

​

Useful Links: Developer Policy, Web API Status Checker

Guides: Bulk and Web API Crossover, Presave Use Case Best Practice, Analytics Use Case Best Practice

2023

Proprietary & Confidential

Spotify

Thank You.

2023

Proprietary & Confidential

Spotify