# Start a sign-in
URL: https://musicapi.com/docs/connect-users/start-sign-in.md

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

Product: MusicAPI Core and MusicAPI Managed Transfers. Section: Connect your users.

1. **Your app**: Links to the sign-in URL
2. **Hosted sign-in**: The user picks a service
3. **Music service**: The user signs in
4. **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.

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

```js
const url = new URL("https://app.musicapi.com/{slug}");
url.searchParams.set("returnUrl", "{returnUrl}");
url.searchParams.set("merchantUserId", currentUser.id); // optional
window.location.assign(url.toString());
```

```python
from urllib.parse import urlencode

url = "https://app.musicapi.com/{slug}?" + urlencode({
    "returnUrl": "{returnUrl}",
    "merchantUserId": current_user_id,  # optional
})
```

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

> **A direct link ignores the on/off switch:** A direct service link works even for a service that is turned off under **Integrations**. The switch only hides the service from the picker.

## Query parameters

- `returnUrl` (string, required): Where the user comes back to, success or failure. It must match one of your **Accepted Return URLs** (rules below).
- `requestOneTimeToken` (boolean): 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](https://musicapi.com/docs/connect-users/raw-tokens-and-refresh.md).
- `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](https://musicapi.com/docs/connect-users/poll-sign-in-status.md).
- `forwardFailures` (boolean): 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}`](https://musicapi.com/docs/reference/get-partner-profile.md): 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](https://musicapi.com/docs/connect-users/handle-callback.md).