External music services

Sonos supports several external music services.

This documentation is not as complete as I wish, but it should get you started. If you’re using this code as a way to get started using external music services, please refer back to this page and or make the documentation even better by sending a PR.

Figuring out the authencation details tooks me a lot of time. If you’re using this in your own application please show your users a link back to this page or start sponsoring me yourself.

Disclaimer

The documentation on this page should allow you to browse external music services with an third party application. You’ll still need to connect the service to your speaker with a supported Sonos application to be able to play music from this service.

The provided documentation is “as-is”, I’m not taking any responsibility. Don’t try to pirate music using the data provided here. Most services encrypt the songs anyway.

Current music services

At the moment the following music services are supported.

Authentication

Sonos locked down communication with most service, by no longer allowing access to the needed access tokens. Those are (my guess) still saved inside the speakers but no longer accessible to external apps. The methods below allow you to get access to those credentials again.

The music services can choose between the following methods of authentication, Sonos advices all partners to migrate to AppLink as a way of authenticating users.

Authenticated requests

After login in with DeviceLink or AppLink, you should have a Key and a Token, these are valid for at least an hour, sometimes much longer.

If the key an token became invalid and you’re trying to use them, you will get a new key and token in the response body in the soap error message and should retry the request (with the new key and token).

For every authenticated request you’ll need the following data from your sonos speaker.

• {DEVICE_ID} - Load this string from the SystemProperties Service with the GetString method, supplying R_TrialZPSerial.
• {HOUSEHOLD_ID} - Load this from the DeviceProperties service.
• {KEY} - Got with AppLink or DeviceLink
• {TOKEN} - Got with AppLink or DeviceLink
• {ACTION_NAME} - The name of the action

Then it’s like every other soap call to the sonos device, do a POST soap request to the MusicService -> SecureURI with the following HTTP headers.

SOAP-Action: "http://www.sonos.com/Services/1.1#%ACTION%"
Content-Type: text/xml; charset=utf8
Accept-Lanugage: en-US
Accept-Encoding: gzip, deflate
User-Agent: Linux UPnP/1.0 Sonos/29.3-87071 (ICRU_iPhone7,1); iOS/Version 8.2 (Build 12D508)

And the following body (with the action body inside off-course):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:s="http://www.sonos.com/Services/1.1">
  <soap:Header>
    <s:context>
      <s:timezone>+01:00</s:timezone>
    </s:context>
    <s:credentials>
      <s:deviceId>{DEVICE_ID}</s:deviceId>
      <s:loginToken>
        <s:token>{TOKEN}</s:token>
        <s:key>{KEY}</s:key>
        <s:householdId>{HOUSEHOLD_ID}</s:householdId>
      </s:loginToken>
    </s:credentials>
  </soap:Header>
  <soap:Body>
    <s:{ACTION_NAME}>
      {ACTION_BODY}
    </s:{ACTION_NAME}>
  </soap:Body>
</soap:Envelope>

Authentication - Save tokens in device

Since you’ll need to save the key and token somewhere, why not use the SystemProperties -> Get/SetString methods to save them? Just a thought.

AppLink

To do AppLink authentication you’ll need to load the following values from the sonos speaker. These values are needed for every request to the service.

• {DEVICE_ID} - Load this string from the SystemProperties Service with the GetString method, supplying R_TrialZPSerial.
• {HOUSEHOLD_ID} - Load this from the DeviceProperties service.

AppLink - Step 1

Do a POST soap request to the MusicService -> SecureURI with the following HTTP headers.

SOAP-Action: "http://www.sonos.com/Services/1.1#getAppLink"
Content-Type: text/xml; charset=utf8
Accept-Lanugage: en-US
Accept-Encoding: gzip, deflate
User-Agent: Linux UPnP/1.0 Sonos/29.3-87071 (ICRU_iPhone7,1); iOS/Version 8.2 (Build 12D508)

And the following body the following body:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:s="http://www.sonos.com/Services/1.1">
  <soap:Header>
    <s:context>
      <s:timezone>+01:00</s:timezone>
    </s:context>
    <s:credentials>
      <s:deviceId>{DEVICE_ID}</s:deviceId>
      <s:loginToken>
        <s:token></s:token>
        <s:key></s:key>
        <s:householdId>{HOUSEHOLD_ID}</s:householdId>
      </s:loginToken>
    </s:credentials>
  </soap:Header>
  <soap:Body>
    <s:getAppLink>
      <s:householdId>{HOUSEHOLD_ID}</s:householdId>
    </s:getAppLink>
  </soap:Body>
</soap:Envelope>

You should get a response that looks like this (Spofity result):

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header />
    <soapenv:Body>
        <getAppLinkResponse xmlns="http://www.sonos.com/Services/1.1">
            <getAppLinkResult>
                <authorizeAccount>
                    <appUrlStringId>SIGN_IN</appUrlStringId>
                    <deviceLink>
                        <regUrl>https://spotify-v5.ws.sonos.com/deviceLink/home?linkCode=xxx</regUrl>
                        <linkCode>xxx</linkCode>
                        <showLinkCode>false</showLinkCode>
                    </deviceLink>
                </authorizeAccount>
                <createAccount>
                    <appUrlStringId>CREATE_NEW</appUrlStringId>
                </createAccount>
            </getAppLinkResult>
        </getAppLinkResponse>
    </soapenv:Body>
</soapenv:Envelope>

This results in:

• regUrl this is the URL you should visit in the browser, it will ask you to login.
• linkCode this is sometimes needed to fill in on the page. And you’ll need it for the next step.

AppLink - Step 2

Continue after logging-in, with the following request.

Do a POST soap request to the MusicService -> SecureURI with the following http headers:

SOAP-Action: "http://www.sonos.com/Services/1.1#getDeviceAuthToken"
Content-Type: text/xml; charset=utf8
Accept-Lanugage: en-US
Accept-Encoding: gzip, deflate
User-Agent: Linux UPnP/1.0 Sonos/29.3-87071 (ICRU_iPhone7,1); iOS/Version 8.2 (Build 12D508)

with the following body:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:s="http://www.sonos.com/Services/1.1">
  <soap:Header>
    <s:context>
      <s:timezone>+01:00</s:timezone>
    </s:context>
    <s:credentials>
      <s:deviceId>{DEVICE_ID}</s:deviceId>
      <s:loginToken>
        <s:token></s:token>
        <s:key></s:key>
        <s:householdId>{HOUSEHOLD_ID}</s:householdId>
      </s:loginToken>
    </s:credentials>
  </soap:Header>
  <soap:Body>
    <s:getDeviceAuthToken>
      <s:householdId>{HOUSEHOLD_ID}</s:householdId>
      <s:linkCode>{LINKCODE_FROM_STEP_ONE}</s:linkCode>
      <s:linkDeviceId>{DEVICE_ID}</s:linkDeviceId>
    </s:getDeviceAuthToken>
  </soap:Body>
</soap:Envelope>

This will result in a privateKey and an authToken, these need to be supplied with every request in the credentials -> loginToken soap header as key and token.

DeviceLink

DeviceLink needs the same data as AppLink, see above.

DeviceLink - step 1

Do a POST soap request to the MusicService -> SecureURI with the following HTTP headers.

SOAP-Action: "http://www.sonos.com/Services/1.1#getDeviceLinkCode"
Content-Type: text/xml; charset=utf8
Accept-Lanugage: en-US
Accept-Encoding: gzip, deflate
User-Agent: Linux UPnP/1.0 Sonos/29.3-87071 (ICRU_iPhone7,1); iOS/Version 8.2 (Build 12D508)

With the following body:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:s="http://www.sonos.com/Services/1.1">
  <soap:Header>
    <s:context>
      <s:timezone>+01:00</s:timezone>
    </s:context>
    <s:credentials>
      <s:deviceId>{DEVICE_ID}</s:deviceId>
      <s:loginToken>
        <s:token></s:token>
        <s:key></s:key>
        <s:householdId>{HOUSEHOLD_ID}</s:householdId>
      </s:loginToken>
    </s:credentials>
  </soap:Header>
  <soap:Body>
    <s:getDeviceLinkCode>
      <s:householdId>{HOUSEHOLD_ID}</s:householdId>
    </s:getDeviceLinkCode>
  </soap:Body>
</soap:Envelope>

This will results in a response with at least the following data:

• regUrl this is the URL you should visit in the browser, it will ask you to login.
• linkCode this is sometimes needed to fill in on the page. And you’ll need it for the next step.

Continue with applink - step 2 after visiting the regUrl in the browser.

Authentication -> UserId

Needs example

Music services reference

For reference we host the supported music services, this file is generated by executing .\bin\run musicservices ip_of_your_sonos --saveJson ..\..\docs\music-services.json from the generator/sonos-docs folder.

To regenerate the table above, run this .\bin\run musicservices 192.168.x.x --docs and replace the part in the docs.