The Run List

Setup guide

One-time setup, about two minutes. You'll need a Spotify Premium account, and a computer or tablet for the middle part (step 2) — Spotify's dashboard doesn't cooperate with phones.

The app also walks you through all of this on first launch — this page is the same journey with screenshots, for anyone who prefers pictures or gets stuck. The screenshots below are taken on a computer.

1 · Install the app

Open app.therunlist.app in your phone's browser, then:

iPhone (Safari)

  1. Tap the Share button (the square with an arrow).
  2. Scroll down and tap Add to Home Screen, then Add.

Android (Chrome)

  1. Tap the ⋮ menu in the top corner.
  2. Tap Add to Home screen (or Install app), then confirm.

Desktop

Just use it in the browser — or click the install icon at the right end of the address bar if your browser offers one.

2 · Create your Spotify app

The Run List connects to Spotify through an app registration that belongs to you — Spotify no longer lets one shared registration serve everyone (they cap each at 5 users). Creating your own is free and private to you. It's for your own personal, non-commercial use — building playlists for your own runs.

Do this step on a computer or tablet. On a phone, Spotify's dashboard doesn't show its “Create app” button until you already have an app — which is exactly the problem when you're making your first one. On a computer or tablet it's right there. Once the app exists, you only need to carry the Client ID back to your phone (email it to yourself, or AirDrop it) to finish setup there.

Open the Spotify Dashboard ↗

  1. Log in with your normal Spotify account. First time here, Spotify may ask you to accept its developer terms.
  2. After logging in, open the account menu (top right) and choose Dashboard: Spotify for Developers: account menu open with Dashboard highlighted
  3. On the Dashboard, click Create app: Spotify Developer Dashboard with the Create app button highlighted
  4. Fill in the form:
    • App name and description — anything you like (e.g. “The Run List”).
    • Redirect URI — exactly this, character for character:
      https://app.therunlist.app/callback
    • Tick Web API, agree to the terms, and save.
    The app settings showing the correct Redirect URI and Web API highlighted
Already have a Spotify app from another project? Spotify allows one per person — just add the Redirect URI above to your existing app and reuse its Client ID.

3 · Connect

  1. On your new app's page in the dashboard, copy the Client ID: The app page with the Client ID field highlighted
  2. Back in The Run List, paste it into the final setup step and tap Connect to Spotify: The Run List setup step 4: paste the Client ID and connect
  3. Log in on Spotify's page and approve the permissions. That's it — you'll land back in the app, connected. From now on it signs in silently.

Troubleshooting

There's no “Create app” button on the dashboard at all
You're almost certainly on a phone. Spotify's dashboard doesn't show that button in its empty state on phone-sized screens, so it's missing for exactly the people creating their first app. Open the dashboard on a computer or tablet and it'll be there. (Odd but true: once you have one app, it shows up on phones fine.)
“Create app” is greyed out, or mentions new integrations being on hold
Spotify occasionally pauses new app registrations platform-wide, showing a note like “New integrations are currently on hold.” That's on Spotify's side — nothing to do with The Run List, and nothing either of us can do but wait. It has lifted after a few days in the past.
“INVALID_CLIENT: Invalid redirect URI” on Spotify's page
The Redirect URI in your Spotify app doesn't exactly match https://app.therunlist.app/callback. Re-copy it — watch for missing characters or stray spaces — save, and try again.
“Spotify didn't recognise the Client ID.”
Re-copy the Client ID from your dashboard (it's 32 letters and numbers). You can change it in the app under Settings → Change Client ID.
“The sign-in didn't complete properly / expired.”
Usually means the page was closed or reloaded mid sign-in. Just tap Connect to Spotify again.
“Your Spotify connection has expired.”
Normal from time to time — reconnect and carry on.
Spotify's login page looks zoomed-out or stretched on my phone
Cosmetic, and outside the app's control — it works fine, and The Run List rights itself automatically a moment after you return.
Everything worked but connecting still fails on a free Spotify account
Spotify requires the owner of an app registration to hold Premium — with your own registration, that's you. See the FAQ.
Some of my playlists are greyed out with a lock
Spotify only shares the contents of playlists you own or collaborate on — followed and editorial playlists can't be used as sources. Copy their songs into a playlist of your own and use that.

Still stuck? Email hello@therunlist.app.