Skip to main content

​
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. Authentication: OAuth 2.0 authorization code flow using your own Spotify Developer app (bring your own Client ID and Client Secret). Serval refreshes the access token automatically using the stored credentials. Data sync: On demand only. There is no background sync, polling, or webhooks - Serval talks to Spotify only when a workflow step runs.

​
What the Spotify integration enables

Anything defined in the Spotify Web API can be accessed through Serval, within the permissions Serval requests (see the gotchas below).

​
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.
Open the Serval connect dialog first and copy the Redirect URI shown there - Spotify’s app creation form asks for a Redirect URI, and this is the value to give it.
1

Create the app

Go to the Spotify Developer Dashboard, log in with the Spotify account you want to use, and click Create app.
2

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.
3

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.
4

Copy your credentials

From the app’s settings page, copy the Client ID, then reveal and copy the Client Secret.
Spotify rejects the sign-in unless the Redirect URI registered on your app matches Serval’s exactly. Always copy it from the read-only field in the connect dialog (it ends in /oauth/callback) rather than typing it by hand.

​
Connect in Serval

1

Open the connect dialog

In Serval, add the Spotify integration. A dialog titled “Connect Spotify” opens.
2

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.
3

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.
4

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.
To rotate the Client ID or Client Secret later, run the connect flow again with the new values - there is no in-place credential edit for this integration.

​
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.”
Play Song has a real side effect: it starts actual playback on one of the connected account’s devices. Do not run it against an account whose devices are in use.
If Test Spotify Connection passes but Get Available Devices reports no devices, or Play Song fails, the usual cause is that no device is available: open the Spotify app on a phone, desktop, or speaker, log in to the connected account, then re-run the check. Playback additionally requires Spotify Premium.

​
Gotchas and troubleshooting

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.
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.
Play, pause, volume, transfer, and other player actions require Spotify Premium, and they only work on a device where the Spotify app is open and logged in to the connected account. Some devices (certain speakers and TVs) are “restricted” and cannot be controlled at all; the Play Song on Spotify workflow skips them and fails if every device is restricted.
Running the Play Song check starts playback of “Never Gonna Give You Up” on an available device for the connected account. It only runs when you trigger it manually; the daily scheduled health-check sweep skips it. Avoid running it while those devices are in use.
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.
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 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.