Skip to content
← Public packages

@kody/spotify

Read a Spotify profile, search the catalog, and manage library, playlists, devices, and playback.

FollowFork

IntegrationsTopics: spotify, music, oauth, playback, playlist, search, library, multi-account

Version
1.0.0
License
MIT
Published
September 10, 2026
Pinned commit
00dae08
Rating
No ratings yet
Forks
0
Adaptation effort
—

README

Agent docs

@kody/spotify

Official Spotify icon (green circle with three sound waves) from Spotify brand assets.

Intent

Provide reusable, account-agnostic Spotify helpers so Kody can read a connected profile, search the catalog, manage library and playlists, list devices, and control playback.

This listing is meant to be forked. After you fork, connect your Spotify developer app and run ./get-profile on your copy. Do not treat the live @kody/spotify integration as yours. There are no hard-coded personal playlists or account aliases.

What it does

  • Read the connected user's profile, recently played tracks, top items, or liked songs
  • Search tracks, albums, artists, or playlists
  • List playlists and devices, then start or transfer playback
  • Preview playlist writes and playback changes with dryRun: true

Do not use this package as a Spotify app that other people log into. Spotify Development Mode is for the app owner (and up to five registered users).

Prerequisites / setup

Spotify has no built-in Kody platform app. You create a personal app in the Spotify developer dashboard and connect it with authorization code + PKCE. PKCE is a public-client flow, so no client secret is stored.

Costs and limits (since February 2026)

  • Development Mode requires the app owner to hold Spotify Premium. If Premium lapses, the app stops working until it is restored.
  • Developers can create up to 25 client IDs; all Development Mode apps share one API quota budget.
  • Refresh tokens expire six months after the original authorization (refreshing an access token does not extend this). Reconnect about twice a year.
  • Some Web API endpoints are unavailable in Development Mode. See the February 2026 migration guide.
  • Extended Quota Mode is only for organizations with at least 250k monthly active users. Personal use stays in Development Mode.

Create the Spotify app

  1. Open the Spotify developer dashboard and click Create app.
  2. Set the redirect URI to exactly https://kody.codes/connect/oauth. Spotify requires HTTPS and rejects localhost.
  3. Select Web API, accept the developer terms, and copy the client ID. With PKCE you do not need the client secret.
  4. Only if someone other than the app owner will authorize: add them under User Management (max 5).

Connect to Kody

flow=pkce is Kody's default, so the link needs no flow parameter and no client secret. Open this URL while signed in to Kody, paste the client ID into the setup form, then authorize.

Guide starter (read-mostly):

https://kody.codes/connect/oauth?provider=spotify&authorizeUrl=https%3A%2F%2Faccounts.spotify.com%2Fauthorize&tokenUrl=https%3A%2F%2Faccounts.spotify.com%2Fapi%2Ftoken&scopes=user-read-recently-played%20user-read-playback-state%20user-library-read&allowedHosts=api.spotify.com

Decoded: authorize https://accounts.spotify.com/authorize, token https://accounts.spotify.com/api/token, scopes user-read-recently-played user-read-playback-state user-library-read, host api.spotify.com.

Recommended for this package (adds profile/top/playlist reads plus playback and library/playlist writes):

https://kody.codes/connect/oauth?provider=spotify&authorizeUrl=https%3A%2F%2Faccounts.spotify.com%2Fauthorize&tokenUrl=https%3A%2F%2Faccounts.spotify.com%2Fapi%2Ftoken&scopes=user-read-recently-played%20user-read-playback-state%20user-read-currently-playing%20user-library-read%20playlist-read-private%20user-top-read%20user-modify-playback-state%20playlist-read-collaborative%20playlist-modify-public%20playlist-modify-private%20user-library-modify&allowedHosts=api.spotify.com

Changing scopes means reconnecting. Reconnect later at https://kody.codes/connect/oauth?provider=spotify (or ?provider=spotify-work).

Access tokens last one hour. Use createAuthenticatedFetch — do not cache raw tokens. Refresh tokens hard-expire six months after the original authorization.

Agents: see AGENTS.md for import paths, multi-account / device targeting, dryRun snippets, and edge cases.

Done when

  • Spotify developer app redirect URI is exactly https://kody.codes/connect/oauth
  • spotify (or spotify-*) OAuth is connected; host api.spotify.com approved
  • ./get-profile returns id and product (premium expected for Development Mode)
  • Mutations preview with dryRun: true before live playlist or playback changes

Branding

The community icon is Spotify's official green circle with three sound waves from Spotify brand assets. Paths are unmodified. Spotify® is a trademark of Spotify AB. This package is not affiliated with or endorsed by Spotify.

Troubleshooting

  • INVALID_CLIENT: Invalid redirect URI: the dashboard redirect URI must be exactly https://kody.codes/connect/oauth.
  • 403 User not registered in the Developer Dashboard: add the user under User Management, or have them create their own app.
  • 403 on a specific endpoint: that endpoint may be unavailable in Development Mode.
  • App failing across the board: check that the app owner's Premium subscription is active.
  • 401 after about an hour: access tokens expire hourly. Use createAuthenticatedFetch.
  • invalid_grant about six months after connecting: reconnect at /connect/oauth?provider=spotify.
Report this listing

Log in to report this listing.