Connect Spotify to Port OS with your own Spotify developer app

Link Spotify to Port OS to search music, manage playlists and control Spotify Connect devices.

Create your Spotify app

You create an app in the Spotify developer dashboard, then give Port OS its client ID and client secret. You need a Spotify account.

1. Copy the Redirect URI from Port OS

Copy this link to set up the Spotify account.

Text

https://auth.portoperatingsystem.com/plugins

2. Create an app in the Spotify dashboard

3. Name the app

Enter an app name and a description. Anything works, for example Port OS and Connects my Spotify account to Port OS. The website field is optional.

4. Add the Redirect URI and choose Web API

Paste the Redirect URI from step 1 into Redirect URIs and click Add. Under Which API/SDKs are you planning to use?, tick Web API.

5. Accept the terms and save

Tick the box to accept Spotify's Developer Terms of Service and Design Guidelines, then click Save.

6. Copy the client ID and client secret

The app opens on Basic Information. Copy the Client ID. Then click View client secret and copy the secret. Treat the secret like a password: do not paste it into chat, a document or a screenshot.

7. Add the Spotify accounts that will connect

New apps start in Development mode, which only lets accounts you add sign in. Open the User Management tab, enter the name and email of each Spotify account that will connect, and click Add user. A development-mode app accepts up to five users. Add the account you will sign in with in step 9.

8. Enter the credentials in Port OS

Back in Port OS, paste the client ID into OAuth client ID and the client secret into OAuth client secret, then click Save credentials. Port OS stores the secret on the backend and never shows it again. The credentials are now saved and nothing is authorized yet: continue with the next step now, or come back later and choose Connect to Spotify. You do not need to enter them again.

9. Approve access on Spotify

Spotify opens and asks you to approve the access Port OS requests (see Required scopes). Sign in with an account you added in step 7, then approve the request. Port OS then shows Spotify as connected, and your playlists and playback devices become available.

Redirect URI

The Redirect URI in the Spotify dashboard must match the value the Port OS connect screen shows, character for character, including the scheme, host, path and any trailing slash. Spotify sends you back to the Port OS auth host, which relays the result to the website. Copy it from that screen rather than from another guide or an older setup.

Required scopes

Port OS requests these scopes. You do not configure scopes in the dashboard; approve them on the Spotify consent screen.

user-read-playback-state
app-remote-control
user-modify-playback-state
playlist-read-private
playlist-read-collaborative
playlist-modify-private
playlist-modify-public
user-library-modify

Quota and development mode

New Spotify apps start in development mode. Under Spotify's July 2026 update, only users on the app's allowlist can sign in until Spotify grants the app extended quota. Spotify counts quota limits itself; see Spotify's quota modes and the July 2026 Web API quota update for current limits.

Troubleshooting

Redirect mismatch (Spotify shows "INVALID_CLIENT: Invalid redirect URI"). The dashboard Redirect URI differs from the one Port OS shows. Copy it again from the connect screen and save the dashboard app.
Invalid client (invalid_client). The client ID or secret is wrong, or the secret was regenerated. Re-enter both from the dashboard and save again before authorizing.
AUTH_LINK_NOT_READY. The connection is still a draft that is missing required values, usually the client secret. Save both client ID and secret, then authorize.
Spotify refuses sign-in for your account. The app is in development mode and your Spotify account is not on its allowlist. See Quota and development mode.
Stale callback. An authorization that was started earlier, or opened twice, can return to Port OS after it expired or was replaced. Close the tab and choose Connect to Spotify again to start a fresh attempt; the previous one is not reused.