About Spotify
Spotify is a music and audio streaming platform. Serval connects to a single Spotify account through a Spotify Developer app that you create and own - you supply the app’s Client ID and Client Secret, and Serval handles the sign-in flow with Spotify. Once connected, workflows can search the Spotify catalog, read and edit playlists and the saved library, and control playback on the account’s devices. Serval only ever sends this connection’s token to one host: api.spotify.com.The Spotify integration is currently in beta.
What the Spotify integration enables
| Capability | Description |
|---|---|
| Generic API requests | A single “Spotify API request” action sends any request to the Spotify Web API, so workflows are not limited to a fixed action list. Paginated results page through with limit and offset values. |
| Search the catalog | Find tracks, artists, albums, playlists, shows, episodes, and audiobooks from keyword queries - for example, turning a song name plus artist into a playable track. |
| Control playback | List Spotify Connect devices, check playback state, start or resume, pause, skip, seek, set repeat and shuffle, transfer playback between devices, and set volume. Requires Spotify Premium and the Spotify app open on a device. |
| Playlists and library | Read private and collaborative playlists, create and edit public and private playlists, and read or modify saved tracks, albums, episodes, shows, and audiobooks. |
| Profile and listening data | Read the connected account’s profile, currently playing track, recently played tracks, queue, and top artists and tracks. |
| Play Song on Spotify (installable workflow) | A pre-built workflow that searches for a song and plays it on a chosen or active device. Inputs: song name (required), artist name, device name (case-insensitive match), and volume (0-100). It skips restricted devices and reports a failure if every device is restricted. |
Get your credentials
Serval does not ship a built-in Spotify app, so you first create one in the Spotify Developer Dashboard. The app issues the Client ID and Client Secret you will paste into Serval, and it must list Serval’s Redirect URI in its settings.Create the app
Go to the Spotify Developer Dashboard, log in with the Spotify account you want to use, and click Create app.
Fill in the app details
Enter an app name (for example “Serval Integration”) and a description. In the Redirect URIs field, paste the Redirect URI you copied from the Serval connect dialog. Accept the Developer Terms of Service and create the app.
Check the Redirect URI
If you created the app before copying Serval’s Redirect URI, open the app’s settings, add it under Redirect URIs, and save.
Connect in Serval
Open the connect dialog
In Serval, add the Spotify integration. A dialog titled “Connect Spotify” opens.
Copy the Redirect URI
The read-only Redirect URI field has a Copy button (it shows “Copied” for a moment after clicking). The helper text reads “Add this as a Redirect URI in your Spotify app settings.” - make sure that is done before continuing.
Enter your credentials
Fill in Client ID (required) and Client Secret (required, masked as you type). Surrounding whitespace is trimmed automatically, and the Connect to Spotify button stays disabled until both fields are filled in (whitespace-only entries count as blank). If a blank value does slip through, it is rejected with “Please fill in all required fields” in the dialog, or “clientId is required” / “clientSecret is required” from the server.
Approve on Spotify
Click Connect to Spotify (the button reads “Connecting…” while in flight). You are sent to Spotify to approve the requested permissions, then returned to Serval. The connection is named after your Spotify profile’s display name, falling back to the Spotify user ID if no display name is set.
Finish the flow within 10 minutes of clicking Connect to Spotify. Pending credentials expire after exactly 10 minutes; taking longer produces “Invalid or expired OAuth state” or “OAuth session expired, please try again”, and you must start the connection over.
Verifying the connection
The integration ships three health checks:- Test Spotify Connection - confirms Serval can authenticate with the Spotify API and reports the connected account. Success: “Successfully connected to Spotify as [name]” (“unknown user” if the profile has no display name). Failure: “Unable to connect to Spotify. Please verify your OAuth credentials are valid and have not been revoked.”
- Get Available Devices - lists the account’s Spotify Connect devices. Success: “Found [number] device(s): [names]”. Zero devices still passes, with the message “API access verified but no devices found. Open Spotify on a device and log in to the connected account to see devices here.” Failure: “Unable to list devices. Please verify your credentials have the user-read-playback-state scope.”
- Play Song - picks the active device (or the first one found) and starts real playback of “Never Gonna Give You Up” to prove end-to-end playback control. Success: “Now playing “Never Gonna Give You Up” on [device name]”. If no devices are found: “No active devices found. Open Spotify on a device and log in to the connected account, then try again.” Failure: “Unable to start playback. This requires Spotify Premium and the Spotify app open and logged in to the connected account.”
Gotchas and troubleshooting
The Redirect URI must match exactly
The Redirect URI must match exactly
Spotify refuses to start the sign-in if the Redirect URI is not registered on your app verbatim. Copy it from the read-only field in the Serval connect dialog and paste it into the Spotify app’s settings - do not retype it or trim it.
The connect flow expires after 10 minutes
The connect flow expires after 10 minutes
Serval holds your pending credentials for exactly 10 minutes between submitting the dialog and Spotify redirecting back. If you pause mid-flow (for example, to edit your Spotify app’s settings), you may see “Invalid or expired OAuth state” or “OAuth session expired, please try again” - just start the connection over.
Playback control needs Premium plus an open, non-restricted device
Playback control needs Premium plus an open, non-restricted device
The Play Song health check actually plays music
The Play Song health check actually plays music
Running the Play Song check starts playback of “Never Gonna Give You Up” on an available device for the connected account. Avoid running it while those devices are in use.
Rotating the Client Secret breaks existing connections
Rotating the Client Secret breaks existing connections
Serval stores your Client ID and Client Secret with the connection and reuses them to refresh the access token automatically. If you revoke or rotate the secret in the Spotify dashboard, token refresh stops working for existing connections. There is no in-place credential edit - reconnect through the dialog with the new credentials.
Permissions are fixed - some areas are out of reach
Permissions are fixed - some areas are out of reach
Serval requests a fixed set of 13 Spotify permissions covering profile, email, playlists, library, playback, and listening history; you cannot narrow or extend them in the dialog. Calls outside that set fail with a permissions error - for example, reading followed artists or following and unfollowing artists and users needs follow permissions Serval does not request. A connection created before a permission was added to Serval’s set will also fail related calls (for example, listing devices needs the playback-state permission) until you reconnect.
The connection is a single Spotify user account
The connection is a single Spotify user account
The connection is identified by the Spotify account that approves the sign-in: it takes that account’s user ID and display name, and every workflow call acts as that one user. To automate a different account, create a separate connection signed in as that account.
Need help? Contact support@serval.com for assistance with your Spotify integration.