Skip to the content
Get an API key
  1. Docs
  2. Connect your users

Start a sign-in

Core + Managed TransfersGuide · 2 min
Send the user to your hosted sign-in URL. They pick a music service, sign in, and come back to your return URL. All query parameters.
  1. 01
    Your app
    Links to the sign-in URL
  2. 02
    Hosted sign-in
    The user picks a service
  3. 03
    Music service
    The user signs in
  4. 04
    Your return URL
    You get the connected-user id

Build the URL

Use your account slug in the path. Signed in, the examples show your slug and your first return URL.

https://app.musicapi.com/{slug}?returnUrl={returnUrl}

The sign-in URL is a page, not an API call. Open it in the user's browser, a new tab, a popup, or a web view.

Skip the picker

Add the service id to the path to send the user straight to one service:

URL for one service
https://app.musicapi.com/{slug}/spotify/auth?returnUrl={returnUrl}

Use the integration type as the id: spotify, appleMusic, youtube, tidal, amazonMusic, deezer, soundCloud, boomplay, audiomack, audius, qobuz.

Query parameters

returnUrl
stringrequired

Where the user comes back to, success or failure. It must match one of your Accepted Return URLs (rules below).

requestOneTimeToken
boolean · false

Add a oneTimeToken to the callback. It lives 30 seconds and lets an app without a backend read the raw service tokens once. See Raw tokens and refresh.

uniqueId
string (UUID v4)

A UUID v4 that you make. Poll the sign-in state with it while the user signs in. See Poll the sign-in status.

forwardFailures
boolean · false

Send the user back to returnUrl at once when the sign-in fails. Without it, the hosted page shows the failure first.

merchantUserId
string

Your own id for this user. It is added to the connected user's list of merchant ids (one connected user can carry several, if several of your users connect the same music account) and written on every usage record of that user, so you can match usage to your users.

Return URL rules

Add return URLs under Settings → Accepted Return URLs in the dashboard. A returnUrl is accepted when one entry matches all of these:

  • The same scheme: https matches only https. A custom app scheme such as myapp:// works for mobile apps.
  • The same host. An entry *.example.com matches every subdomain of example.com, but not example.com itself.
  • The path starts with the entry's path. The entry https://example.com/music accepts https://example.com/music/callback.

Your verified custom domain counts as an accepted return URL on its own. A returnUrl that matches nothing fails with 400 and internalCode: 12 (InvalidReturnUrl).

Check a URL before you use it with GET/app/users/{slug}: with returnUrl it answers 400 when the URL does not match.

What happens next

The user comes back to returnUrl with a data64 query parameter. Read it in Handle the callback.