Sonos Music API - Reference

getDeviceAuthToken

Sonos uses getDeviceAuthToken to authenticate users so they can use your service. See implementing authentication for details. Sonos makes this request on your secure (https:) endpoint.

request Parameters

Name

Type

Description

householdId

string

The Sonos household ID requesting the link code.

linkCode

string

The authorization code you returned in your getAppLink response.

If a link code is not provided, it indicates Sonos is upgrading the authentication mode for a player's records. In this case, the request Header will also include the <username> and <password> in the <credentials>. See Upgrading from DeviceLink, Session ID, or anonymous access for details.

linkDeviceId

string

(Optional) The player sends back the value you provided in the <deviceLink> object in your getAppLink response. Use the <linkDeviceId> to ensure that the device you originally gave the token to is the same device sending you the request.

Response

Name

Type

Description

authToken

string

The authorization token for the household. The maximum length is 2048 characters.

privateKey

string

The key field can be used to hold any additional information necessary to use the token. The maximum length is 2048 characters.

userInfo

complex. See details below.

(Optional, but recommended) Use this object to return the user's nickname on your service. The Sonos app will pre-populate this nickname for the account holder when they add your service to their Sonos household.

<userInfo>

Name

Type

Description

userIdHashCode

string

Your service's immutable opaque identifier of the user. Sonos will use this for personalization options available in a future release.

We strongly urge you to avoid putting any identifying information in this string. For additional security, Sonos does not store this information in its raw form but stores a hash value of this string.

nickname

string(32)

(Optional) The user's screen name. If you provide this field, Sonos will use it to pre-fill the account nickname during account setup.

Any other fields that may be in the WSDL are not yet implemented and are reserved for future use.

Sample Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <soapenv:Header>
      <ns:credentials>
         <ns:deviceId>00:00:00:00:00</ns:deviceId>
         <ns:deviceProvider>Sonos</ns:deviceProvider>
      </ns:credentials>
   </soapenv:Header>
   <soapenv:Body>
      <ns:getDeviceAuthToken>
         <ns:householdId>Sonos_abc123</ns:householdId>
         <ns:linkCode>KJ12U</ns:linkCode>
         <ns:linkDeviceId>123AQ311</ns:linkDeviceId>
      </ns:getDeviceAuthToken>
   </soapenv:Body>
</soapenv:Envelope>

Sample valid Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <getDeviceAuthTokenResponse xmlns="http://www.sonos.com/Services/1.1">
         <getDeviceAuthTokenResult>
            <authToken>123ASDF7987897hkjhkjhkj</authToken>
            <privateKey>KEY</privateKey>
         </getDeviceAuthTokenResult>
      </getDeviceAuthTokenResponse>
   </soap:Body>
</soap:Envelope>

Sample Valid Response WITH USER INFO

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <getDeviceAuthTokenResponse xmlns="http://www.sonos.com/Services/1.1">
         <getDeviceAuthTokenResult>
            <authToken>123ASDF7987897hkjhkjhkj</authToken>
            <privateKey>KEY</privateKey>
            <userInfo>
               <userIdHashCode>911a30baf1d8ced73d016a07650787e7</userIdHashCode>
               <nickname>John Smith</nickname>
            </userInfo>
         </getDeviceAuthTokenResult>
      </getDeviceAuthTokenResponse>
   </soap:Body>
</soap:Envelope>

NOT_LINKED_RETRY fault

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>Client.NOT_LINKED_RETRY</faultcode>
         <faultstring>Link Code not found retry...</faultstring>
         <detail>
            <ExceptionInfo>NOT_LINKED_RETRY</ExceptionInfo>
            <SonosError>5</SonosError>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

NOT_LINKED_FAILURE Fault

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>Client.NOT_LINKED_FAILURE</faultcode>
         <faultstring>Link Code not found retry...</faultstring>
         <detail>
            <ExceptionInfo>NOT_LINKED_FAILURE</ExceptionInfo>
            <SonosError>6</SonosError>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>