> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/spotify.md).

# Spotify

Register a Spotify app for the Appmixer Spotify connector (OAuth 2).

## OAuth app properties

| Property                | Value                                                                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Multi-tenant**        | **Conditional.** One app serves all your users only in *Extended Quota Mode*. A new app is in *Development Mode* and works for at most 5 users that you add by hand.                 |
| **Vendor review**       | **Required** for more than 5 users: a quota extension request. Spotify accepts it only from registered organizations with a launched service and at least 250k monthly active users. |
| **Review time**         | Up to 6 weeks.                                                                                                                                                                       |
| **Users before review** | 5, each added on the app's **Settings → User Management** tab.                                                                                                                       |
| **App owner**           | A Spotify account with an active Premium subscription. The app stops working when the subscription lapses.                                                                           |
| **Regions**             | One app works worldwide.                                                                                                                                                             |
| **Client secret**       | No expiry documented. It can be rotated in the dashboard.                                                                                                                            |
| **Rate limits**         | Per app, over a rolling 30-second window; lower in Development Mode. Spotify publishes no numbers.                                                                                   |
| **Checked**             | 2026-11-13                                                                                                                                                                           |

**Limitations**

* Without Extended Quota Mode, each of your customers needs their own Spotify app, with their own Premium account and their own 5 users.
* A connected account stops working 6 months after the user gave consent, because Spotify's refresh token has a fixed lifetime that use does not extend. The user then connects the account again. This applies to apps created since 2026-06-18 and to older apps since 2026-07-20.
* A user who is not on the User Management list can still log in. The first API call then fails with `403`.
* Development Mode apps have lost some Web API endpoints and fields (batch reads of tracks, albums and artists, new releases, categories, other users' profiles and playlists, `popularity`, `followers`). This matters for **Make API Call**.

Sources: [Quota modes](https://developer.spotify.com/documentation/web-api/concepts/quota-modes), [February 2026 changes](https://developer.spotify.com/documentation/web-api/tutorials/february-2026-migration-guide), [Refresh token expiration](https://developer.spotify.com/blog/2026-06-18-refresh-token-expiration). What the rows mean: [OAuth app properties](https://docs.appmixer.com/connector-configuration/oauth-app-properties.md).

## Register the Spotify app

1. Sign in to the [Spotify for Developers Dashboard](https://developer.spotify.com/dashboard) with the Spotify account that will own the app.
2. Click **Create app** and fill in:
   * **App name** and **App description**: anything your users should recognise — both are shown to the user on the Spotify consent screen.
   * **Website**: optional, for example your product page.
   * **Redirect URIs**: `https://<your-appmixer-api>/auth/spotify/callback` — replace the host with your Appmixer API URL and keep the suffix `/auth/spotify/callback` (for example `https://api.acme.appmixer.cloud/auth/spotify/callback`). Click **Add** next to the field. Spotify only accepts `https://` redirect URIs (plain `http://` is allowed only for loopback addresses), and the URI must match exactly, including the absence of a trailing slash.
   * **Which API/SDKs are you planning to use?**: tick **Web API**.
   * Accept the Spotify Developer Terms of Service and click **Save**.
3. On the app's page open **Settings → Basic Information**. Copy the **Client ID**, click **View client secret** and copy the **Client secret**.

### Scopes

Scopes are not configured in the dashboard — the connector requests them when a user connects an account. The Spotify connector requests:

* `playlist-read-private` — list the user's private playlists (**List Playlists** and the **Playlist** dropdown of the other components).
* `playlist-modify-public` and `playlist-modify-private` — **Create Playlist**, **Add Items To Playlist**, **Replace Playlist Items** on public and private playlists.
* `user-library-modify` — **Delete Playlist** (Spotify removes a playlist from the user's library through `DELETE /me/library`).

**Find Tracks** and **List Playlist Items** need no extra scope. **Make API Call** runs with the same four scopes, so calls to endpoints that need other scopes (playback, listening history, …) fail with `403`.

{% hint style="warning" %}
**Development Mode limits.** Every new Spotify app starts in *Development Mode*. Since February 2026 such an app works only while its **owner has an active Spotify Premium subscription**, and at most **5 Spotify users** can use it. Each of them has to be added on the app's **Settings → User Management** tab (name and the e-mail address of their Spotify account) before they connect the account in Appmixer — a user who is not on the list can log in, but every API call then fails with `403`.

To open the app to more users, request *Extended Quota Mode* (**Settings → Quota extension Request**). Spotify accepts these requests only from registered organizations with a launched service and at least 250k monthly active users, and the review can take up to six weeks. See [Quota modes](https://developer.spotify.com/documentation/web-api/concepts/quota-modes).
{% endhint %}

### Rate limits

Spotify does not publish a fixed rate limit; it is computed over a rolling 30-second window and is lower for Development Mode apps. The connector throttles itself to 60 requests per 30 seconds per Appmixer user and retries `429` responses after the `Retry-After` interval.

### Useful links

* [Spotify Web API — Apps](https://developer.spotify.com/documentation/web-api/concepts/apps)
* [Redirect URIs](https://developer.spotify.com/documentation/web-api/concepts/redirect_uri)
* [Scopes](https://developer.spotify.com/documentation/web-api/concepts/scopes)
* [Quota modes](https://developer.spotify.com/documentation/web-api/concepts/quota-modes)
* [February 2026 Web API Dev Mode changes](https://developer.spotify.com/documentation/web-api/tutorials/february-2026-migration-guide)

## Backoffice configuration

Configuration ID: `appmixer:spotify` (Backoffice → Configuration; see [Connector Configuration](https://docs.appmixer.com/getting-started/services) for how a configuration is created and how its keys reach the connector).

* `clientId` — Client ID of the Spotify app registered above. Not needed when Spotify is authenticated through the Appmixer Auth Hub.
* `clientSecret` — Client secret of the same app. Not needed with the Auth Hub.
* `listCacheTTL` — Optional. How long, in milliseconds, the list of the user's playlists shown in the **Playlist** dropdown is cached. Default `120000` (2 minutes).
* `outputFilePrefix` — Optional. File name prefix of the CSV file that **Find Tracks**, **List Playlists** and **List Playlist Items** create when their output is set to *File*; the file is named `<prefix>-<component name>.csv`. Default `spotify-objects-export`.

The same keys can be set with the CLI (`-u` updates the existing configuration instead of creating it):

```bash
appmixer service-config set appmixer:spotify -u -d '{
  "clientId": "<client id>",
  "clientSecret": "<client secret>"
}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/connector-configuration/spotify.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
