# MusicAPI - Complete Documentation > This is the complete documentation for MusicAPI, a unified API platform for 19+ music streaming services. For a summary, see https://musicapi.com/llms.txt --- # Introduction MusicAPI provides a unified API platform that enables you to **integrate with multiple music streaming services** through a single, consistent interface. ## Getting Started MusicAPI offers two types of endpoints to serve different integration needs: 1. **Public endpoints** - Access music content and metadata without user authentication 2. **User endpoints** - Access users' personal music libraries and data To use user endpoints, you must first implement our Single Sign-On (SSO) Music Authorization system. Once configured, you can make authenticated requests to access user-specific data. To start using the API, please create an account at https://app.musicapi.com --- # Authorization MusicAPI requires authentication credentials for all API requests. You can obtain your Client ID and Client Secret from https://app.musicapi.com after creating your developer account. ## Public Endpoints Public endpoints that access general music content (such as the Search API) require only **Client ID** authentication. These endpoints are safe to call directly from your frontend application. ### Required Headers Each API call must include the following headers: - `Authorization: Token [Your Client ID]` - `Content-Type: application/json; charset=utf-8` ```bash title="Example Request" curl "https://api.musicapi.com/search/introspection" \ -H 'Content-Type: application/json; charset=utf-8' \ -H 'Authorization: Token 2cf82db3-4064-4235-8253-16994eb51773' ``` ## Private Endpoints Private endpoints that access user-specific data (such as user profiles, playlists, and libraries) require enhanced security authentication. MusicAPI supports two authentication methods for private endpoints: ### Method 1: Client Secret Authentication (Backend Only) You can authenticate using your Client ID and Client Secret combination. Since this provides full account access, **you must only use this method on your secure backend servers**. This is ideal for server-side operations like fetching user information for internal processing. ### Method 2: JWT Dev Token Authentication (Recommended) The **recommended approach** is to use JWT Dev Tokens. Generate the token on your backend server, then pass it to your frontend application for secure API calls. **Example Implementation**: In Next.js applications, you can generate the JWT token server-side using `getServerSideProps` and securely pass it to your client components. ## Dev Token Authentication **Recommended for frontend applications!** JWT Dev Tokens provide secure authentication for frontend applications while maintaining security best practices. ### Step 1: Generate Key Pair Create a private/public key pair using the following OpenSSL commands: ```bash openssl ecparam -name prime256v1 -genkey -noout -out private.ec.key openssl ec -in private.ec.key -pubout -out public.pem ``` ### Step 2: Configure Public Key 1. Navigate to Account Settings in your developer dashboard 2. Add your public key to your account configuration 3. Save the configuration and note down the **Key ID** - you'll need this for JWT generation ### Step 3: Generate JWT Tokens MusicAPI uses the **ES256** algorithm for JWT validation. You must use this specific algorithm for all token generation. **Required JWT Header:** ```json { "typ": "JWT", "alg": "ES256", "kid": "Your Public Key ID from Account Settings" } ``` **Required JWT Payload:** ```json { "iss": "Your Client ID", "sub": "Target User UUID [integrationUserUUID] (optional)", "iat": 1683873013557, // Current timestamp: new Date().getTime() / 1000 "exp": 1685082613557 // Expiration: date.addDays(new Date(), 14).getTime() / 1000 } ``` **Note**: The `sub` property is optional. When omitted, the token can query data for any user within your account scope. ### Step 4: API Authentication Include the following headers in your API requests: - `Authorization: DevToken [Your Generated JWT]` - `Content-Type: application/json; charset=utf-8` ### Example Implementation Here's a TypeScript example for generating Dev Tokens: ```typescript import jwt from 'jsonwebtoken'; import date from 'date-and-time'; export const signDevToken = (clientId: string, keyId: string, privateKey: string, integrationUserUUID?: string) => { const algorithm = 'ES256'; return jwt.sign( { iss: clientId, iat: Math.floor(new Date().getTime() / 1000), exp: Math.floor(date.addDays(new Date(), 14).getTime() / 1000), sub: integrationUserUUID, }, privateKey, { algorithm, header: { alg: algorithm, kid: keyId, }, } ); }; ``` ## Client Secret Authentication **Warning: Never expose your Client Secret in frontend code!** Treat it like a password - it provides full access to your account and should only be used on secure backend servers. Client Secret authentication provides access to both public and private endpoints. Due to its privileged access level, this method should **only be used on secure backend servers**. ### Implementation Use HTTP Basic Authentication by sending your Client ID and Client Secret in the Authorization header: ```bash Authorization: Basic base64($clientId + ':' + $clientSecret) ``` ### Example Requests ```bash # Using pre-encoded credentials curl "https://api.musicapi.com/search/introspection" \ -H 'Authorization: Basic OGQ4ODMxNzgtOTU4NS00ODJlLWJiNGItMGM4NTczNmVkYzJkOjlmYWNmZTI4LTgzZTUtNGIzZi04MTVmLTIzNTUxZDc3Y2Q0OA==' \ -H 'Content-Type: application/json; charset=utf-8' # Using curl's built-in authentication curl "https://api.musicapi.com/search/introspection" \ -u "ClientID:ClientSecret" \ -H 'Content-Type: application/json; charset=utf-8' ``` --- # Rate Limiting MusicAPI implements rate limiting to ensure fair usage and maintain service quality for all users. ## Public Endpoints _Applies to endpoints starting with `/public/`_ To prevent abuse and ensure optimal resource allocation, we enforce the following rate limits: **Current Limit**: 1 request per minute per IP address ### Increased Limits For higher usage requirements, please consider our [RapidAPI integration](https://rapidapi.com/freeyourmusic-freeyourmusic-default/api/musicapi13/pricing), which offers flexible pricing plans to accommodate various usage levels. ## User Endpoints **Default Rate Limit**: 300 requests per minute for new accounts ### Enterprise Rate Limits If your application requires higher rate limits, please contact our business team at [business@musicapi.com](mailto:business@musicapi.com) to discuss enterprise solutions. ## Music Service Rate Limits Individual music streaming services may impose their own rate limiting restrictions. When we encounter rate limits from upstream services (such as Spotify, Apple Music, etc.), we standardize the response format and provide: - **HTTP Status Code**: 429 (Too Many Requests) - **Retry-After Header**: Indicates when to retry the request (following the [HTTP specification](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After)) This ensures consistent error handling regardless of which music service encounters the rate limit. --- # Supported Music Services MusicAPI provides comprehensive integration support across multiple music streaming platforms, offering both public and authenticated endpoints for different use cases. ## Public Endpoint Coverage Public endpoints support **19 music services** and provide access to general music content without user authentication: Amazon Music, Apple Music, Deezer, Pandora, SoundCloud, Spotify, Tidal, YouTube, YouTube Music, Napster, Qobuz, QQ Music, Yandex Music, VK Music, Zvuk, JioSaavn, Boomplay, Audiomack, Audius ## Authenticated Endpoint Coverage Private endpoints support **13 music services** and provide access to user-specific data with proper authentication: Spotify, Apple Music, YouTube, Tidal, Qobuz, Amazon Music, Boomplay, Napster, Deezer, SoundCloud, Audiomack, Audius, Resso ## API Introspection Use the introspection endpoint to programmatically retrieve the current list of supported services and validate your integration configuration: ```bash title="Introspection Request" curl "https://api.musicapi.com/search/introspection" \ -H 'Content-Type: application/json; charset=utf-8' \ -H 'Authorization: Token YOUR_CLIENT_ID' ``` ```json title="Introspection Response" { "sources": [ "amazonMusic", "appleMusic", "deezer", "pandora", "soundCloud", "spotify", "tidal", "youtube", "youtubeMusic", "napster", "qobuz", "qqMusic", "yandexMusic", "vkMusic", "zvuk", "jiosaavn", "boomplay", "audiomack" ], "authSources": [ "spotify", "appleMusic", "youtube", "tidal", "boomplay", "amazonMusic", "napster", "deezer", "soundCloud", "audiomack" ], "types": ["track", "album"] } ``` --- # Music Service Feature Compatibility Music streaming services vary significantly in their API capabilities and supported features. Before implementing specific functionality in your application, consult the compatibility table below to verify that your target services support the required features. | Service | Update playlists | Remove playlists | Remove tracks in playlist | Move tracks in playlist | Add tracks to library | Remove tracks from library | Fetch library albums | Fetch albums | Fetch album tracks | Add album to library | Remove album from library | Fetch library artists | Fetch artists | Add artist to library | Remove artist from library | Search by ISRC | Returns ISRC | Returns preview URL | Returns user email | Returns user country | Max pagination limit | |---------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | Spotify | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | - | - | 50 | | Apple Music | - | - | - | - | Y | - | Y | Y | Y | Y | - | Y | Y | - | - | Y | Y | - | - | Y | 25 | | YouTube | Y | Y | Y | Y | - | - | - | - | - | - | - | - | - | - | - | - | - | - | Y | - | 50 | | Tidal | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | Y | - | Y | Y | 20 | | Resso | - | - | Y | - | - | - | - | - | - | - | - | - | - | - | - | Y | Y | - | - | - | 50 | | Boomplay | Y | - | Y | - | Y | - | Y | Y | Y | Y | - | - | Y | - | - | Y | Y | - | - | - | 50 | | Amazon Music | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | Y | - | 100 | | Napster | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | Y | Y | - | - | Y | Y | Y | Y | Y | 50 | | Deezer | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | Y | Y | Y | 50 | | SoundCloud | Y | Y | Y | Y | Y | Y | - | - | - | - | - | Y | Y | Y | Y | - | Y | - | - | Y | 50 | | Audiomack | Y | Y | Y | - | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | Y | - | Y | Y | 50 | | Audius | Y | Y | Y | - | Y | Y | - | - | - | Y | Y | - | - | - | - | - | Y | - | Y | Y | 50 | | Qobuz | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | Y | - | Y | Y | 500 | --- # Getting Started with Music SSO MusicAPI gives you one Single Sign-On (SSO) flow for these music streaming services: spotify, appleMusic, youtube, tidal, boomplay, amazonMusic, napster, deezer, soundCloud, audiomack, audius, qobuz ## What you need You do not need a developer account with any music service. MusicAPI holds the provider credentials and uses them solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You never store provider tokens. What you bring: - A MusicAPI developer account with a **business name** and **logo**. Listeners see both on the authorisation screen. - The music services you want to offer, enabled in the dashboard. - A whitelisted **return URL** on your side to receive the callback. If you already run your own developer app with a music service, you can use it instead. Each service page has an **Advanced** section for that. It is optional. **To begin your integration, please visit https://app.musicapi.com/admin/ and create your developer account.** Account creation is free and takes a few minutes. ## Step 1: Account Registration **Business Name** - Choose a recognizable business name, as music services will display "[Your Business Name] wants to access your data" to listeners during the OAuth flow. Select something your listeners will recognise and trust. ## Step 2: Dashboard Overview After successful registration, you'll be redirected to your developer dashboard where you can: - Complete your account setup by uploading custom logos and branding - Enable the music services you want to offer, and test each login flow - Add the return URLs that MusicAPI may redirect listeners to - Monitor your API usage and integration status ## Step 3: Redirect a listener Follow Initializing Authentication to build the redirect URL, and Authentication Callback to read the result. # Initializing User Authentication **Note:** This guide assumes you have already configured your music service integrations in the Developer Dashboard. ## Basic Authentication Flow To initiate the user authentication process, redirect users to the following URL structure: `https://app.musicapi.com/integrations/{slug}?returnUrl={returnUrl}` **Example Implementation:** If your account slug is `sanreh` and you want users to return to `https://sanreh.com/callback`: `https://app.musicapi.com/integrations/sanreh?returnUrl=https://sanreh.com/callback` Users will then be presented with a list of configured music services to choose from. After completing authentication (whether successful or failed), they will be redirected to your specified return URL. **Caution:** Ensure your return URL is added to the list of accepted URLs in your Developer Dashboard for security purposes. ## Service-Specific Authentication For enhanced user experience, you may want to direct users to authenticate with a specific music service (for example, when displaying service-specific buttons in your application interface). Use the following URL structure to bypass service selection: `https://app.musicapi.com/integrations/{slug}?returnUrl={returnUrl}&ms={musicService}` **Example Implementation:** To direct users specifically to Apple Music authentication: `https://app.musicapi.com/integrations/sanreh?returnUrl=https://sanreh.com/callback&ms=appleMusic` Replace `musicService` with any of the [supported services](./getting-started.mdx). **Warning:** Pre-selecting a service bypasses the "enabled/disabled" settings in your dashboard. Even if you've disabled certain integrations in your dashboard, they will still function when users are directed to them via direct URLs. **Info:** The branding and logos shown in the authentication flow are fully customizable through your Developer Dashboard. ## Advanced Configuration Options Enhance your authentication flow with these optional parameters: - **Error Forwarding**: Add `forwardFailures=true` to redirect users back to your return URL immediately upon authentication errors - **Status Polling**: Pass a unique UUID v4 as `uniqueId=[uuidv4()]` to enable polling for authentication status updates ([see related endpoint](/docs/endpoints/get-auth-flow-status)) --- # Authentication Callback After successful user authentication, users are redirected back to the `returnUrl` that you specified in the initial authentication request. **Info:** Click the link below to test the complete login flow (you will be redirected back to this page). ## Callback Parameters When users are redirected to your return URL, MusicAPI includes the following parameters: ### Data Parameter (`data64`) A base64-encoded JSON string containing authentication results and user information. Decode this parameter to access the authentication data. ```json title="Decoded Data Parameter Example" { "integrationUserUUID": "6a002d4b-f95b-471f-a27d-609a42e10cdb", "authModel": { "uuid": "a1869581-38b2-4268-aee2-a4c2355efeb0", "status": "success", "error": null }, "integration": { "type": "spotify", "returnUrl": "https://apirc.musicapi.com/app/integrations/fym/spotify/callback" } } ``` ### Parameter Definitions - **`integrationUserUUID`**: Unique identifier for the authenticated music service user - **`authModel`**: Authentication session information - **`uuid`**: Unique identifier for this authentication session - **`status`**: Authentication result status - `success`: Authentication completed successfully and user information was retrieved - `error`: Authentication failed or user information could not be retrieved - `initialised`: Authentication was started but never completed (rarely seen in callbacks) - **`error`**: Error message for debugging purposes (present when status is "error") - **`integration`**: Music service integration details ## Retrieving User Information After obtaining the `authModelUUID` from the callback parameters, you can retrieve detailed user information using our API. ### Security Considerations The `authModelUUID` is a UUID4 identifier that provides access to user data without requiring additional authentication tokens. **Keep this UUID secure** - anyone with access to this UUID can retrieve the associated user information. ### API Endpoint Make a GET request to retrieve user data: ``` https://api.musicapi.com/app/integrations/[authModelUUID] ``` ### Response Structure The API response includes the following properties: #### **returnUrl** _(string)_ The original return URL you specified during authentication initialization. #### **authModel** _(object)_ The same authentication model object from the callback parameters. #### **integrationUser** _(object)_ User data from the music streaming service. Available fields vary by service: - **`integrationUserId`**: The user's unique ID within the music service (useful for direct API calls) - **`name`**: User's display name (may be empty for some services like Apple Music or Tidal) - **`email`**: User's email address (may be empty for services like Apple Music) - **`imageUrl`**: User's profile picture URL (optional) - **`country`**: Two-letter ISO country code #### **user** _(object)_ Information about your MusicAPI account profile. #### **integration** _(object)_ Your integration configuration details (**sensitive data is never included**). ### Example Request ```bash title="Retrieve User Information" curl "https://api.musicapi.com/app/integrations/a1869581-38b2-4268-aee2-a4c2355efeb0" ``` ### Response ```json title="Example response" { "returnUrl": "fym://test?data=...", "authModel": { "uuid": "a1869581-38b2-4268-aee2-a4c2355efeb0", "status": "success", "error": null }, "integrationUser": { "id": 4, "integrationUserId": "1176177544", "name": "Example User", "email": "user@example.com", "imageUrl": "https://example.com/profile-image.jpg", "country": "PL" }, "user": { "id": 2, "slug": "fym", "name": "FreeYourMusic", "logoFile": { "id": 2, "uuid": "6b352535-8bbf-4af7-aa22-08b1aec4a287", "url": "https://api.musicapi.com/files/6b352535-8bbf-4af7-aa22-08b1aec4a287/download" }, "base64Logo": "data:image/jpeg;base64,...[BASE64_IMAGE_DATA]...", "logoSquareFile": { "id": 3, "uuid": "e6c44d51-9dac-4bfa-8a5d-abfb0920ad99", "url": "https://api.musicapi.com/files/e6c44d51-9dac-4bfa-8a5d-abfb0920ad99/download" } }, "integration": { "type": "spotify", "returnUrl": "https://api.musicapi.com/callback/spotify", "data": { "clientId": "828ce85ee93b4fb6bf043ac5d8ba2599", "scopes": [ "playlist-read-collaborative", "playlist-modify-public", "playlist-read-private", "playlist-modify-private", "user-read-private", "user-read-email", "user-library-modify", "user-library-read", "user-top-read", "user-read-recently-played" ] } } } ``` --- # Accessing Original Authentication Tokens For advanced integrations, you may need direct access to the original authentication tokens from music streaming services. This is useful when you need to call music service APIs directly for functionality not yet supported by MusicAPI. ## Backend Implementation (Client Secret Authentication) ### Use Case Access original authentication tokens when you need to make direct API calls to music streaming services for unsupported endpoints or advanced functionality. ### Endpoint `GET /public/integrations/user/{userModelUUID}` ### Example Request ```bash title="Retrieve User Authentication Data" curl "https://api.musicapi.com/public/integrations/user/e892f4a5-887f-4df5-9062-f8e3fff8c68a" \ -H 'Content-Type: application/json; charset=utf-8' \ -H 'Authorization: Basic [BASE64_ENCODED_CLIENT_CREDENTIALS]' ``` ### Example Response ```json title="Authentication Data Response" { "integrationUser": { "integrationUserId": "1163433669", "userUUID": "e892f4a5-887f-4df5-9062-f8e3fff8c68a", "name": "Bartosz Hernas", "email": "b@hern.as", "imageUrl": "https://example.com/profile-image.jpg", "country": "pl", "authData": { "accessToken": "REDACTED_FOR_SECURITY" }, "authDataExpiresAt": 1696320099094 } } ``` ### Security Requirements **Warning:** This endpoint requires Client Secret authentication and must **only be called from your secure backend servers**. Never expose Client Secret credentials in frontend code. ## From your frontend - using oneTimeToken If you frontend app has a need to save the original auth tokens, and you do not have your own backend, you can request the login page with additional parameter: `requestOneTimeToken` set to `true`. `https://app.musicapi.com/integrations/{slug}?returnUrl={returnUrl}&requestOneTimeToken=true` Now in the returned `data64` param, it will contain one additional property, `oneTimeToken`: ```json title="Parsed Data Param" { "integration": { "type": "spotify", "returnUrl": "https://api.musicapi.com/callback/spotify" }, "authModel": { "uuid": "6fe4e706-ebe3-40b2-aa0f-f74177aa8708", "status": "success", "error": null }, "integrationUserUUID": "e75315f0-d1e1-4063-b801-181ad1a954e1", "oneTimeToken": "e50cc5e7-254a-4cff-a000-457ae53a059d" } ``` You can use it _only once_ to fetch the auth data and it expires in 1 minute, so make sure to use it immediately. Just pass the token in `Authorization` header as `Token {oneTimeToken}`. ```bash title="Fetch User Auth Data Request with one time token" curl "https://api.musicapi.com/public/integrations/user/e892f4a5-887f-4df5-9062-f8e3fff8c68a" -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization: Token e50cc5e7-254a-4cff-a000-457ae53a059d' ``` --- # Spotify MusicAPI holds the Spotify credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a Spotify developer account, and you never store Spotify tokens. ## Enable Spotify 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark Spotify as **Enabled** so listeners see it as an option. 3. Use the **Test Spotify** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to Spotify To open the Spotify authorisation flow directly: https://app.musicapi.com/{slug}/spotify/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## Spotify specifics - Spotify shows "MusicAPI wants to access your data" style consent copy with **your** business name and logo, taken from your dashboard account. - Podcast and audiobook objects are out of scope. Only tracks, albums, artists and playlists are read or written. - Since February 2026 Spotify's own Development Mode is capped at 5 users and needs a Premium account. That limit does not apply to listeners authorising through MusicAPI. ## Advanced: use your own Spotify developer app You do not need this for a standard integration. Use it only when you already run a Spotify developer app and want listeners to authorise that app instead of the MusicAPI one. ### Steps for your own Spotify app 1. Log in to the [Spotify for Developers Dashboard](https://developer.spotify.com/dashboard) and click **Create an App**. 2. Set the Redirect URI to exactly: > https://api.musicapi.com/callback/spotify 3. Open the app's **Settings** page and copy the **Client ID** and **Client Secret**. Then, in the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/), open **Integrations**, paste the credentials into the Spotify integration and save. # Apple Music MusicAPI holds the Apple Music credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a Apple Music developer account, and you never store Apple Music tokens. ## Enable Apple Music 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark Apple Music as **Enabled** so listeners see it as an option. 3. Use the **Test Apple Music** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to Apple Music To open the Apple Music authorisation flow directly: https://app.musicapi.com/{slug}/appleMusic/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## Apple Music specifics - Apple Music uses Sign in with Apple plus a MusicKit user token. MusicAPI handles the developer token, storefront selection and library-versus-catalogue ID mapping for you. - The Apple Music API does not let third parties rename or re-describe an existing playlist. Creating playlists and adding tracks works. ## Known problems If you use your own Apple developer key and see: ``` { "message": "Invalid token specified" } ``` make sure the key has both `Media Services` and `Sign in with Apple` enabled: ## Advanced: use your own Apple Music developer app You do not need this for a standard integration. Use it only when you already run a Apple Music developer app and want listeners to authorise that app instead of the MusicAPI one. ### Steps for your own Apple Music app You need a paid Apple Developer Program membership. 1. Find your **Team ID** at [developer.apple.com/account](https://developer.apple.com/account#MembershipDetailsCard). 2. Generate a **Key ID** and **Private Key** in the Apple Certificates Portal: [Create a Media Identifier and Private Key](https://developer.apple.com/help/account/configure-app-capabilities/create-a-media-identifier-and-private-key/). 3. Register a Services ID to get the **Client ID**: [Register a Services ID](https://developer.apple.com/help/account/manage-identifiers/register-a-services-id). 4. When configuring Sign in with Apple on the Services ID, make sure that: - **Domains & Subdomains** lists both `api.musicapi.com` and `app.musicapi.com` - **Return URL** is `https://api.musicapi.com/callback/apple_sign_in` Then, in the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/), open **Integrations**, paste the credentials into the Apple Music integration and save. # YouTube Music MusicAPI holds the YouTube Music credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a YouTube Music developer account, and you never store YouTube Music tokens. ## Enable YouTube Music 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark YouTube Music as **Enabled** so listeners see it as an option. 3. Use the **Test YouTube Music** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to YouTube Music To open the YouTube Music authorisation flow directly: https://app.musicapi.com/{slug}/youtube/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## YouTube Music specifics - There is no official YouTube Music API. YouTube Music playlists and liked songs are YouTube playlists, read and written through the YouTube Data API. - Video-only and user-uploaded items return an explicit unmatched reason instead of being silently omitted. - The YouTube Data API has a daily quota per Google project. MusicAPI manages that quota for you. ## Advanced: use your own YouTube Music developer app You do not need this for a standard integration. Use it only when you already run a YouTube Music developer app and want listeners to authorise that app instead of the MusicAPI one. ### Steps for your own YouTube Music app 1. In the [Google API Console](https://console.cloud.google.com/apis/credentials) click **Create project**. 2. On the [Enabled APIs](https://console.cloud.google.com/apis/dashboard) page click **ENABLE APIS AND SERVICES**, search for "YouTube Data API v3" and enable it. 3. Open **OAuth consent screen**, pick the user type, set the app name and a developer contact email. 4. Click **ADD OR REMOVE SCOPES** and add: > https://www.googleapis.com/auth/youtube > https://www.googleapis.com/auth/userinfo.email > https://www.googleapis.com/auth/userinfo.profile > https://www.googleapis.com/auth/youtube.readonly > https://www.googleapis.com/auth/youtube.upload > https://www.googleapis.com/auth/youtube.force-ssl 5. Add **Test Users** while the app is unverified. 6. Go to **Credentials**, click **Create Credentials** → **OAuth client ID**, choose **Web application**, name it (for example "MusicAPI Login") and set the Redirect URI to exactly: > https://api.musicapi.com/callback/youtube 7. Copy the **Client ID** and **Client Secret**. Then, in the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/), open **Integrations**, paste the credentials into the YouTube Music integration and save. # Tidal MusicAPI holds the Tidal credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a Tidal developer account, and you never store Tidal tokens. ## Enable Tidal 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark Tidal as **Enabled** so listeners see it as an option. 3. Use the **Test Tidal** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to Tidal To open the Tidal authorisation flow directly: https://app.musicapi.com/{slug}/tidal/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## Tidal specifics - Hi-res and MQA variants of one recording resolve to one ID, so repeated writes stay idempotent. ## Advanced: use your own Tidal developer app You do not need this for a standard integration. Use it only when you already run a Tidal developer app and want listeners to authorise that app instead of the MusicAPI one. ### Steps for your own Tidal app 1. Log in to the [Tidal for Developers Portal](https://developer.tidal.com/dashboard) and click **Create App**. 2. Set the Redirect URI to exactly: > https://api.musicapi.com/callback/tidal 3. Open **App Overview** and copy the **Client ID** and **Client Secret**. Then, in the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/), open **Integrations**, paste the credentials into the Tidal integration and save. # Amazon Music MusicAPI holds the Amazon Music credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a Amazon Music developer account, and you never store Amazon Music tokens. ## Enable Amazon Music 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark Amazon Music as **Enabled** so listeners see it as an option. 3. Use the **Test Amazon Music** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to Amazon Music To open the Amazon Music authorisation flow directly: https://app.musicapi.com/{slug}/amazonMusic/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## Amazon Music specifics - The Amazon Music API is a closed beta. MusicAPI's partner access covers library reads and writes for your listeners. - Prime, Unlimited and HD tiers expose different catalogues. MusicAPI reads whichever the listener's account allows. ## Advanced: use your own Amazon Music developer app You do not need this for a standard integration. Use it only when you already run a Amazon Music developer app and want listeners to authorise that app instead of the MusicAPI one. ### Steps for your own Amazon Music app Your own Security Profile only lets listeners log in with Amazon. Library access still requires an Amazon Business Development agreement, which MusicAPI already holds. 1. Log in to the [Amazon Developer Portal](https://developer.amazon.com/dashboard) and click **Create New Security Profile**. 2. Click **Save**, open **Web Settings** and add this entry to **Allowed Return URLs**: > https://api.musicapi.com/callback/amazonMusic 3. Copy the **Client ID** and **Client Secret**. Then, in the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/), open **Integrations**, paste the credentials into the Amazon Music integration and save. # Deezer MusicAPI holds the Deezer credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a Deezer developer account, and you never store Deezer tokens. ## Enable Deezer 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark Deezer as **Enabled** so listeners see it as an option. 3. Use the **Test Deezer** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to Deezer To open the Deezer authorisation flow directly: https://app.musicapi.com/{slug}/deezer/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## Deezer specifics - Flow and editorial playlists are read-only upstream. User playlists and favourites support both reads and writes. - Deezer does not return ISRCs, so matching into Deezer runs on normalised text. ## Advanced: use your own Deezer developer app You do not need this for a standard integration. Use it only when you already run a Deezer developer app and want listeners to authorise that app instead of the MusicAPI one. ### Steps for your own Deezer app 1. Log in to [Deezer for developers](https://developers.deezer.com) and click **Create a new application**. 2. Set the Redirect URI to exactly: > https://api.musicapi.com/callback/deezer 3. Open the application and copy the **Application ID** and **Secret Key**. Then, in the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/), open **Integrations**, paste the credentials into the Deezer integration and save. # SoundCloud MusicAPI holds the SoundCloud credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a SoundCloud developer account, and you never store SoundCloud tokens. ## Enable SoundCloud 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark SoundCloud as **Enabled** so listeners see it as an option. 3. Use the **Test SoundCloud** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to SoundCloud To open the SoundCloud authorisation flow directly: https://app.musicapi.com/{slug}/soundCloud/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## SoundCloud specifics - SoundCloud has closed public API registration. MusicAPI's existing access covers your listeners. - Independent uploads often have no equivalent on other services. Match responses say so per item. ## Advanced: use your own SoundCloud developer app You do not need this for a standard integration. Use it only when you already run a SoundCloud developer app and want listeners to authorise that app instead of the MusicAPI one. ### Steps for your own SoundCloud app Only useful if SoundCloud already approved an app for you. 1. Open [SoundCloud for developers](https://soundcloud.com/you/apps/new) and create the application. 2. Set the Redirect URI to exactly: > https://api.musicapi.com/callback/soundCloud 3. Copy the **Client ID** and **Client Secret**. Then, in the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/), open **Integrations**, paste the credentials into the SoundCloud integration and save. # Napster MusicAPI holds the Napster credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a Napster developer account, and you never store Napster tokens. ## Enable Napster 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark Napster as **Enabled** so listeners see it as an option. 3. Use the **Test Napster** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to Napster To open the Napster authorisation flow directly: https://app.musicapi.com/{slug}/napster/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## Napster specifics - Legacy Rhapsody IDs are mapped forward automatically, so older libraries still resolve. ## Advanced: use your own Napster developer app You do not need this for a standard integration. Use it only when you already run a Napster developer app and want listeners to authorise that app instead of the MusicAPI one. ### Steps for your own Napster app 1. Log in to the [Napster for Developers Portal](https://developer.prod.napster.com/developer) and click **Create**. 2. Copy the **API Key** and **API Secret**. Then, in the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/), open **Integrations**, paste the credentials into the Napster integration and save. # Audiomack MusicAPI holds the Audiomack credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a Audiomack developer account, and you never store Audiomack tokens. ## Enable Audiomack 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark Audiomack as **Enabled** so listeners see it as an option. 3. Use the **Test Audiomack** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to Audiomack To open the Audiomack authorisation flow directly: https://app.musicapi.com/{slug}/audiomack/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## Audiomack specifics - Audiomack API access is granted per partner. MusicAPI's partner credentials cover your listeners; there is no own-app option. - Mixtape and album structures are normalised into the same album object as every other provider. # Boomplay MusicAPI holds the Boomplay credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a Boomplay developer account, and you never store Boomplay tokens. ## Enable Boomplay 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark Boomplay as **Enabled** so listeners see it as an option. 3. Use the **Test Boomplay** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to Boomplay To open the Boomplay authorisation flow directly: https://app.musicapi.com/{slug}/boomplay/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## Boomplay specifics - Boomplay has no public developer program. MusicAPI's partner credentials cover your listeners; there is no own-app option. - Many Boomplay releases have no ISRC. Matching runs on artist plus normalised title. # Qobuz MusicAPI holds the Qobuz credentials used to authenticate your listeners. They are used solely to facilitate music transfers a listener has authorised, the same way FreeYourMusic works. You do not need a Qobuz developer account, and you never store Qobuz tokens. ## Enable Qobuz 1. Open the [MusicAPI Developer Dashboard](https://app.musicapi.com/admin/) and go to **Integrations**. 2. Mark Qobuz as **Enabled** so listeners see it as an option. 3. Use the **Test Qobuz** button to run the login flow once with your own account. Listeners see your business name and logo on the authorisation screen. Set both under **Account** in the dashboard. ## Redirect listeners to Qobuz To open the Qobuz authorisation flow directly: https://app.musicapi.com/{slug}/qobuz/auth?returnUrl={returnUrl} Or let listeners pick from every service you enabled: https://app.musicapi.com/{slug}?returnUrl={returnUrl} After authorisation the listener returns to your `returnUrl`. See Authentication Callback for the payload. ## Qobuz specifics - Qobuz API access is partner-only. MusicAPI's partner credentials cover your listeners; there is no own-app option. - Classical metadata (composer, work, movement) is preserved on read and used to improve match confidence.