getDeviceAuthToken

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

Request parameters

Name	Type	Description
`householdId`	string(255)	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 Upgrade to OAuth 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.
`callbackPath`	string	(Optional) Reserved for future use.

Response

Include the response in a deviceAuthTokenResult inside a deviceAuthTokenResponse element.

Name	Type	Description
`authToken`	string(2048)	The authorization token for the household. All subsequent requests will contain this element. The maximum length is 2048 characters.
`privateKey`	string(2048)	The key field can be used to hold any additional information necessary to use the token. This element should only be used to refresh tokens. This element should not be expected in every request sent by Sonos. The maximum length is 2048 characters.
`userInfo`	complex	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
`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.
`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.
`accountType`	enum	Deprecated (Optional) If you support different account tiers, you can return them here. Values are: `premium`, `trial`, `free`
`accountStatus`	enum	Deprecated (Optional) You can send the account status to Sonos. Values are: `active`, `restricted`, `expired`
`profileUrl`	string(2048)	Deprecated. (Optional) A URL to the user's profile.
`pictureUrl`	string(2048)	Deprecated. (Optional) A URL to the user's profile.

Any other fields that may be in the WSDL are not yet implemented and are reserved for future use. Download the WSDL from SOAP requests and responses.

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