Use authentication tokens

After your service completes its response to getDeviceAuthToken, Sonos sets the SOAP header of the rest of the Sonos Music API calls to include a credentials element. This element contains the information needed for your service to continue to authenticate the user for all Sonos API calls. Here are the credentials header sub-elements relevant to authentication:

loginToken — The authentication information for the user making the request. This includes the following sub-elements:

  • token – The initial value is from the user authToken your service returned for the getDeviceAuthToken call made when authenticating the user. Your service manages the token.
  • key – The initial value is from the privateKey your service returned in the same getDeviceAuthToken call. Your service manages the key.
  • householdId – The household ID associated with the user’s current Sonos system. This is the same value the Sonos app sends to your service in the getAppLink request.

For the complete list of credentials sub-elements see the SOAP header section in SOAP requests and responses. The authentication API calls getAppLink and getDeviceAuthToken are the only calls that will not typically contain credentials. (If a Sonos player is in the process of upgrading the authentication mode, getDeviceAuthToken includes credentials as described in Upgrade to OAuth.)

Validate the authentication token

Ensure the token supplied is valid for this user. Initially, tokens are created by your authorization service and supplied in the authToken during your service’s getDeviceAuthToken processing. If the token does not a match for this user, return a SOAP fault to indicate the account is not valid. Return the Client.LoginUnauthorized faultcode. In the faultstring, add a log message for the Sonos app and player log files. Sonos displays this message in Sonos diagnostics sent by users for debugging and troubleshooting.

As an option, you may also wish to use the householdId to further validate the token but it this is not required. For example, you may choose to store the householdId value and associate it with the token when it is generated. Then, your service can later check the stored householdId against the value supplied in future API requests that use that token.

Refresh expired authentication tokens

To maintain session security, authentication tokens should have a short life. This section explains how to refresh tokens and to re-authenticate Sonos with your service without user interaction, providing for an uninterrupted user experience.

Sonos offers your service two different ways to refresh tokens. Generally, you can refresh tokens using a SOAP fault. If your service needs to refresh a token during an HTTP request, Sonos sends a refreshAuthToken request to your service to update the token.

Note: Sonos players propagate new credentials to other Sonos players and Sonos apps, but Sonos apps do not. If your service refreshes a request from a Sonos app (indicated by a device name in the user-agent), you may need to honor the same refresh token when handling a token refresh request from Sonos players.

See Initialize refresh tokens to continue.

If you don’t use refresh tokens, require manual log in

If you do not implement refresh tokens, when the token expires, return the Client.AuthTokenExpired fault in response to getMetadata and getMediaURI to indicate the user must manually log in and authenticate again. In the faultstring, add a log message for this fault code.

You do not need to return this fault in response to getLastUpdate or getMediaMetadata. When the Sonos speaker makes sends a getMediaMetadata request and it fails, it does not start playback. The user will also see that playback failed.

Initialize refresh tokens

To start using refresh tokens, your authorization service generates a private key and returns it in the privateKey field of your getDeviceAuthToken response along with an authorization token in authToken. Your service needs to maintain an association between the user, the token, and the key. The private key represents the refresh token for this authorization token. You are free to use any format you wish for private keys using up to 2048 characters.

When a user later does something such as a browse request, Sonos includes both the token and the key in the header credentials of every API request, as shown below.

Refresh expired tokens using a SOAP fault

When your service receives an API request, do the following for refresh token processing:

Verify that the token and key in the API request header are valid for this user. If valid, processing is done. If the token and key are not valid, or if the token in the API request header has expired, follow the steps below to refresh the authentication token.

  1. Generate a new authentication token.
  2. Return the Client.TokenRefreshRequired SOAP fault shown below for the current API request:

    • Include the new authentication token in authToken.
    • Include the refresh token in privateKey, even if your service has not changed it. You determine the refresh token policy, but you must return it even if it hasn’t changed.
  3. This fault causes Sonos to update both the token and key credentials in the header for all subsequent API requests.
  4. Sonos retries the initial API request with the new credentials.

If a token refresh fails, what you return will depend on what behavior you want.

Retry the token refresh process

Return a Server.ServiceUnknownError error with a custom message that asks the user to try the action again in a few moments. See the Custom error messages section in Error handling for details. See Handle auth errors for details on errors specific to authentication.

Make the user reauthorize

Return a Client.AuthTokenExpired fault. This causes Sonos to give the user a prompt to re-authorize and go through the authorization process again.

Refresh expired tokens with refreshAuthToken

Sonos calls refreshAuthToken when an HTTP REST request returns a 401 error. The 401 error may indicate an expired authorization token. Your service should send a new authToken and either the existing privateKey or a new one in your response. Sonos will retry the original request using the authToken from your response as the OAuth bearer token in an Authorization header. Sonos will only retry the HTTP request once. If it fails again, Sonos will display a failure message. See REST request for details.

When an HTTP REST request returns a 401 error, the Sonos app sends a refreshAuthToken request like the one shown below. There are no parameters, but Sonos sends the current authToken and privateKey in the header as the token and key elements respectively.

Your service should return a new authToken in your response. You can choose to generate a new privateKey or return the original one. Your service’s response should look something like the sample below. Sonos uses the authToken and privateKey that you send as the token and key values respectively in future SOAP requests. You can also return the userInfo object if your service supports this capability. To simplify this sample, we have chosen not to show this object here.

When you don’t support refreshAuthToken, listeners see the failure message and have to close the Info View window. Your service can use the SOAP fault method to refresh the token when their system sends another SMAPI request. For example, if the listener selects Info View or browses into a container.

If your service doesn’t support refresh tokens at all, the listener must manually log in and authenticate again.