@kody/spotify
Read a Spotify profile, search the catalog, and manage library, playlists, devices, and playback.
Files
@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
- Open the Spotify developer dashboard and click Create app.
- Set the redirect URI to exactly
https://kody.codes/connect/oauth. Spotify requires HTTPS and rejectslocalhost. - Select Web API, accept the developer terms, and copy the client ID. With PKCE you do not need the client secret.
- 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.comDecoded: 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.comChanging 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(orspotify-*) OAuth is connected; hostapi.spotify.comapproved./get-profilereturnsidandproduct(premiumexpected for Development Mode)- Mutations preview with
dryRun: truebefore 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 exactlyhttps://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.403on 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.
401after about an hour: access tokens expire hourly. UsecreateAuthenticatedFetch.invalid_grantabout six months after connecting: reconnect at/connect/oauth?provider=spotify.