Skip to content

README.md

Latest commit

 

History

History
107 lines (77 loc) · 5.05 KB

README.md

File metadata and controls

107 lines (77 loc) · 5.05 KB
Raw

Gatekeeper Spotify

This package provides Spotify Web API integration for Gadgets. Connect a Spotify account and gadgets can search the catalog, read and edit your library and playlists, manage follows, and control playback on your Spotify Connect devices — all behind the approval queue.

It offers two resource granularities:

  • Spotify Account (whole-instance): profile, catalog search, library (saved tracks/albums, top items, recently played), follows, playlists, and playback control via getPlayer().
  • Spotify Playlist: read / edit / follow / unfollow a single playlist.

This gatekeeper is not an authentication provider (providesAuth: false) — Spotify isn't offered as a "Continue with…" sign-in method.

Targets Spotify's post-February-2026 development-mode API. Library writes use the generic PUT/DELETE /me/library, playlist contents use /playlists/{id}/items, etc. Some fields Spotify removed in dev mode (e.g. track popularity, parts of the user profile) are returned as null.

Setting up Spotify OAuth credentials

If you're running this project locally and want to use Spotify integration, you'll need to create your own Spotify app.

Step 1: Create a Spotify app

  1. Go to the Spotify Developer Dashboard and click Create app.

  2. Fill in a name and description (anything).

  3. Redirect URI: add exactly

    http://127.0.0.1:8787/gatekeeper/spotify/oauth

    Spotify does not allow localhost as a redirect URI for new apps — you must use the loopback IP literal 127.0.0.1. Replace host/port with your BASE_URL when not running locally (production must use HTTPS).

  4. Under APIs used, select Web API.

  5. Save, then copy the Client ID and Client secret.

Step 2: Configure your local environment

Create a .env file in this package's directory (packages/gatekeeper-spotify/.env):

CLIENT_ID=your-client-id-here
CLIENT_SECRET=your-client-secret-here
# Must match the redirect URI host you registered. Spotify rejects "localhost", so use 127.0.0.1.
BASE_URL=http://127.0.0.1:8787/gatekeeper/spotify

Note: .env is gitignored and should never be committed. Because the redirect uses 127.0.0.1, open the Workshop at http://127.0.0.1:8787 (not localhost) so the OAuth popup stays on the same host.

Step 3: Add yourself as a user (development mode)

A new Spotify app starts in development mode, which limits it to a small number of users you add explicitly. In the dashboard, under User Management, add the Spotify account (name + email) you intend to connect — otherwise authorization will fail. Lifting this limit requires requesting extended quota from Spotify.

Playback control requires Spotify Premium. Player write commands (play/pause/seek/volume/…) return 403 for free accounts.

Step 4: Verify setup

  1. Start the application in dev mode (see the root README.md).
  2. Create or open a gadget and go to the Connections tab.
  3. Click + New Connection and choose a Spotify resource type (whole account, or a playlist).
  4. If prompted, connect your Spotify account — you'll be redirected to Spotify's authorization page in a new tab; after granting access the tab closes and you're back in Gadgets.
  5. For a playlist resource, use the picker to choose the playlist to connect.
  6. Create the connection.

You can see and manage connected accounts in settings (via the account menu in the upper-right).

Notes & limitations

  • Approvals & simulation. Reads are logged and writes are queued for human approval; nothing is performed on Spotify until approved. Reads optimistically reflect your own pending edits (e.g. a pending playlist add shows in listTracks) so a gadget can keep working before approvals land. Playback commands are gated but not simulated — getState() always shows real device state.
  • Non-owned playlists. Spotify withholds track contents for playlists you don't own/collaborate on, so listTracks() returns an empty list (metadata via getDetails() still works).
  • Spotify Connect quirks. Some third-party Connect endpoints (e.g. Music Assistant) can be invisible to getDevices() and getState().device may misidentify the active device; confirm device transfers with a follow-up getState().

Troubleshooting

"Spotify Gatekeeper Not Configured" page during authorization

CLIENT_ID or CLIENT_SECRET is missing. Ensure packages/gatekeeper-spotify/.env exists with both values, then restart the dev server.

"INVALID_CLIENT: Invalid redirect URI"

The redirect URI sent doesn't exactly match one registered on the app. Confirm the dashboard has http://127.0.0.1:8787/gatekeeper/spotify/oauth and that BASE_URL in .env is http://127.0.0.1:8787/gatekeeper/spotify (note 127.0.0.1, not localhost; no trailing slash).

Authorization fails with "User not registered in the Developer Dashboard"

The connecting Spotify account isn't on the app's User Management list (development-mode limit). Add it in the dashboard and retry.