docs: Update Spotify docs and usage due to Redirect URI changes

As of April 2025 Spotify no longer allows insecure redirect URIs which complicates initial Spotify setup. * Improve spotify App creation instructions * Add several approaches to creating a valid redirect URI * Remove Spotify as the default Source example in docs due to complexity of Redirect URI requirements Closes #330
2026-04-26 10:51:06 +00:00 · 2025-08-01 17:28:16 +00:00 · 2025-08-01 17:28:16 +00:00 · 06b23d6287
commit 06b23d6287
parent 38a15d6426
5 changed files with 101 additions and 26 deletions
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -4,9 +4,9 @@ services:
    container_name: multi-scrobbler
    environment:
      - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-      #- SPOTIFY_CLIENT_ID=
-      #- SPOTIFY_CLIENT_SECRET=
-      #- SPOTIFY_REDIRECT_URI=http://multi-scrobbler-host-IP:9078/callback ## Need to be whitelisted in Spotify dashboard and is used for creating the connection first time
+      #- JELLYFIN_APIKEY=
+      #- JELLYFIN_URL=
+      #- JELLYFIN_USER=
      #- MALOJA_URL=http://maloja:42010
      #- MALOJA_API_KEY=
      #- PUID=1000 # required if running docker on linux host, see main README Docker setup instructions
--- a/docsite/docs/configuration/configuration.mdx
+++ b/docsite/docs/configuration/configuration.mdx
@ -1806,16 +1806,92 @@ The Plex Webhook Source will be removed in an upcoming release. You should migra

 ### [Spotify](https://www.spotify.com)

-To access your Spotify history you must [register an application](https://developer.spotify.com/dashboard) to get a
-Client ID/Secret. Make sure to also whitelist your redirect URI in the application settings.
+<details>

-:::note
+<summary>Spotify and Automix</summary>

 If your Spotify player has [Automix](https://community.spotify.com/t5/FAQs/What-is-Automix/ta-p/5257278) enabled and Spotify uses it for your playlist/queue then MS cannot accurately determine when a track will end. This is because the track is "mixed" in your queue with a shorter play time than its actual length and [Spotify does not report this modified play time in its API.](https://community.spotify.com/t5/Spotify-for-Developers/Wrong-duration-ms-of-track-with-Automix/m-p/5429147) This **does not affect MS's ability to scrobble** from Spotify but it will affect the accuracy of the duration MS reports was played.

-:::
+</details>

-#### Configuration
+#### Authenticate Spotify with Multi-Scrobbler
+
+To access your Spotify history you must [create a Spotify App](https://developer.spotify.com/dashboard) to get a
+Client ID/Secret.
+
+1. **Login to https://developer.spotify.com** with your existing Spotify account and accept Developer Terms
+
+2. Navigate to your Spotify Developer [Dashboard](https://developer.spotify.com/dashboard) and start the **Create App** process
+
+3. Determine the correct **Redirect URI** to use and set it in your App settings
+
+<details>
+
+<summary>Redirect URI Instructions</summary>
+
+A Redirect URI is the URL that Spotify will navigate your **browser** to after you complete authorization. The URL will contain the code necessary for multi-scrobbler to get a Spotify access token.
+
+Spotify [**no longer allows insecure URIs**](https://developer.spotify.com/documentation/web-api/tutorials/migration-insecure-redirect-uri) (start with `http://`) unless the address is `127.0.0.1` -- so `localhost` and internal IPs (`192.168.0.xxx`) no longer work.
+
+Use **one** of the following methods to specify a valid Redirect URI and complete Spotify authentication with multi-scrobbler:
+
+<Tabs groupId="spotifyRedirect" queryString>
+    <TabItem value="https" label="HTTPS">
+        **Use a domain you control, with SSL certificates/HTTPS enabled, to create a valid redirect URI.**
+        
+        For example, if you are already running multi-scrobbler behind a reverse proxy (nginx/traefik/caddy) at `https://scrobbler.mydomain.com` then set the Spotify Redirect URI for your Spotify App, and multi-scrobbler `SPOTIFY_REDIRECT_URI` ENV, to `https://scrobbler.mydomain.com/callback`
+
+        Alternatively, if multi-scrobbler is not accessible behind your domain, then use the [**Echo**](./?spotifyRedirect=echo#spotify) method with your own domain instead of 127.0.0.1.
+    </TabItem>
+    <TabItem value="local" label="Run MS Locally">
+        **Run multi-scrobbler, configured for a Spotify Source, from the same machine as your browser in order to get credentials.**
+        
+        In this scenario you can use `http://127.0.0.1:9078/callback` as the Spotify Redirect URI and multi-scrobbler `SPOTIFY_REDIRECT_URI` ENV.
+        
+        After completing authentication, copy the contents of local multi-scrobbler's [configuration folder](../installation/installation.mdx#storage) to the final location of where multi-scrobbler will be run.
+    </TabItem>
+    <TabItem value="echo" label="Echo">
+        **Use a docker container on the same machine your browser is on to "intercept" the callback URL from Spotify authentication, then manually finish the process by changing the domain to your multi-scrobbler instance.**
+
+
+        1. Create a container on the same machine as your browser using the [`mendhak/http-https-echo:36`](https://github.com/mendhak/docker-http-https-echo) image. This container runs a simple HTTP server that echos back any request it recieves.
+
+        ```shell
+        docker run --rm -p 127.0.0.1:5079:8080 mendhak/http-https-echo:36
+        ```
+
+        2. Set the Spotify Redirect URI and multi-scrobbler `SPOTIFY_REDIRECT_URI` ENV as `http://127.0.0.1:5079/callback`
+
+        3. In [Authenticate Spotify with Multi-Scrobbler](#authenticate-spotify-with-multi-scrobbler) (outside these Redirect Instructions) go to **Step 4** and continue the instructions
+
+        Eventually, Spotify will redirect you to a web page with a URL like `http://127.0.0.1:5079/callback?code=xxxxxx...`
+
+        ![echo](echo.png)
+
+        4. In the URL, replace `127.0.0.1:5079` with the address/IP for your multi-scrobbler instance so the URL is similar to `http://192.168.0.101:9078/callback?code=xxxxxx...`. Then navigate to this URL to complete authentication.
+
+    </TabItem>
+
+    <TabItem value="msEcho" label="Echo from echo.multi-scrobbler.app">
+        For your convenience, I run the [`mendhak/http-https-echo:36`](https://github.com/mendhak/docker-http-https-echo) container from the [**Echo**](./?spotifyRedirect=echo#spotify) approach on a domain I, the multi-scrobbler developer [FoxxMD](https://github.com/FoxxMD), control and self-host. Please be aware:
+        
+        * I **do not collect personal data** or any querystrings/data sent in requests to this site
+        * It's **not possible** for me to use the code sent by Spotify to this URL without also having your Client ID/Secret
+        * However, there is **always** risk involved with trusting a service you do not control. Evaluate the risk of using this site for yourself.
+
+        Use the [**Echo**](./?spotifyRedirect=echo#spotify) approach, starting from **Step 2**, with **https://echo.multi-scrobbler.app/callback** as Spotify Redirect URI and multi-scrobbler `SPOTIFY_REDIRECT_URI` ENV.
+    </TabItem>
+</Tabs>
+
+</details>
+
+4. Save your new App, then copy the Client ID/Secret from the App's Basic Information page.
+
+5. Add the Client ID, Secret, and Redirect URI to the respective field/ENV in the [configuration section below](#spotify-config)
+
+6. Start multi-scrobbler, then visit the Web Dashboard and click **(Re)authenticate** on the Spotify card to start the auth process
+
+#### Configuration {#spotify-config}

 <Tabs groupId="configType" queryString>
 <TabItem value="env" label="ENV">
--- a/docsite/docs/configuration/echo.png
+++ b/docsite/docs/configuration/echo.png
--- a/docsite/docs/installation/installation.mdx
+++ b/docsite/docs/installation/installation.mdx
@ -172,7 +172,7 @@ See the [**Quick Start Guide**](../quickstart.mdx) for another guided docker-com

 The example scenario:

-* [Spotify **Source**](../configuration/configuration.mdx#spotify)
+* [Jellyfin **Source**](../configuration/configuration.mdx#jellyfin)
 * [Maloja **Client**](../configuration/configuration.mdx#maloja)
 * Serving app on port `9078`
 * Docker container located on a different IP (`192.168.0.100`) so use [Base URL](../configuration/configuration.mdx#base-url)
@ -184,7 +184,7 @@ The example scenario:
        <Tabs groupId="configType" queryString>
            <TabItem value="env" label="ENV">
                ```bash
-                docker run --name multi-scrobbler -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" -e "BASE_URL=192.168.0.100" -e "MALOJA_URL=http://domain.tld" -e "MALOJA_API_KEY=1234" -e "PUID=1000" -e "PGID=1000" -p 9078:9078 -v /home/myUser/ms:/config foxxmd/multi-scrobbler
+                docker run --name multi-scrobbler -e "JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56bd6540c" -e "JELLYFIN_URL=192.168.0.101:8096" -e "JELLYFIN_USER=MyUser" -e "BASE_URL=192.168.0.100" -e "MALOJA_URL=http://domain.tld" -e "MALOJA_API_KEY=1234" -e "PUID=1000" -e "PGID=1000" -p 9078:9078 -v /home/myUser/ms:/config foxxmd/multi-scrobbler
                ```
            </TabItem>
            <TabItem value="file" label="File">
@ -204,8 +204,9 @@ The example scenario:
                container_name: multi-scrobbler
                environment:
                    - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-                    - SPOTIFY_CLIENT_ID=yourId
-                    - SPOTIFY_CLIENT_SECRET=yourSecret
+                    - JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56bd6540c
+                    - JELLYFIN_URL=192.168.0.101:8096
+                    - JELLYFIN_USER=MyUser
                    - BASE_URL=http://192.168.0.100:9078
                    - MALOJA_URL=http://domain.tld:42010
                    - MALOJA_API_KEY=1234
@ -261,7 +262,7 @@ See [this issue](https://github.com/FoxxMD/multi-scrobbler/issues/135#issuecomme
 <Tabs groupId="configType" queryString>
 <TabItem value="env" label="ENV">
 ```shell
-SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret MALOJA_URL="http://domain.tld" node src/index.js
+JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56bd6540c JELLYFIN_URL=192.168.0.101:8096 JELLYFIN_USER=MyUser MALOJA_URL="http://domain.tld" node src/index.js
 ```
 </TabItem>
 <TabItem value="file" label="File">
@ -273,12 +274,13 @@ SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret MALOJA_URL="http://dom
    {
        "sources": [
            {
-                "type": "spotify",
+                "type": "jellyfin",
                "clients": ["myConfig"],
-                "name": "mySpotifySource",
+                "name": "myJellyfinSource",
                "data": {
-                    "clientId": "a89cba1569901a0671d5a9875fed4be1",
-                    "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a",
+                    "apiKey": "a89cba1569901a0671d5a9875fed4be1",
+                    "url": "http://192.168.0.101:8096",
+                    "user": "MyUser"
                 }
            }
        ],
--- a/docsite/docs/quickstart.mdx
+++ b/docsite/docs/quickstart.mdx
@ -57,20 +57,17 @@ services:
        ```
    </TabItem>
    <TabItem value="spotify" label="Spotify">
-        To access your Spotify activity you must [register a Spotify application](https://developer.spotify.com/dashboard) to get a
-        **Client ID/Secret**.
+        To access your Spotify activity you must [create a Spotify App](https://developer.spotify.com/dashboard) to get a
+        **Client ID/Secret** and set a valid **Redirect URI**.
+        
+        Refer to the [Spotify Authentication instructions in the docs.](./configuration/configuration.mdx#authenticate-spotify-with-multi-scrobbler)

-        When creating the application add this to **Redirect URIs**
-
-        ```
-        http://192.168.0.100:9078/callback
-        ```
-
-        After the application is created add these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
+        Assuming you used the **HTTPS** method for your **Redirect URI** from the instructions above...after the application is created add these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)

        ```yaml title="~/msData/docker-compose.yml"
        - SPOTIFY_CLIENT_ID=yourClientId
        - SPOTIFY_CLIENT_SECRET=yourClientSecret
+        - SPOTIFY_REDIRECT_URI=https://multi-scrobbler.mydomain.com/callback
        ```

        Later, after [starting multi-scrobbler](#start-multi-scrobbler), visit the dashboard at `http://192.168.0.100:9078` and click **(Re)authenticate** on the Spotify card to authorize multi-scrobbler to use your account. Monitoring will begin automatically after authorization is complete.