Add authentication

When users add your service to their household, they enable Sonos to access their account. Sonos can send the user to your mobile app or to a webpage to enter credentials using OAuth authentication.


OAuth authentication upgrade

If you haven't already, we highly recommend upgrading your implementation to OAuth.

If your service uses DeviceLink or Session ID authentication, your existing implementations will continue to work. However, we still recommend upgrading to OAuth.

OAuth authentication methods

There are two ways to offer OAuth authentication:

App authenticationMobileSonos opens a deep link to your app to perform authentication.

We recommend pairing with browser authentication.
Browser authenticationDesktop
Sonos directs users to a webpage to enter their credentials for authentication.

Sonos uses one API call to provide both of these options. While browser authentication is the minimum requirement, we encourage you to offer both browser and app authentication for the best user experience.

How Sonos OAuth works

The following is a summary of Sonos's authentication process:

  1. The user attempts to add a partner music service to their Sonos app.
  2. The Sonos app sends a getAppLink request to the partner's SMAPI service.
  3. The SMAPI service's response values populate the user's screen with authentication path choices.
  4. The user's selection directs them to log into the music service via partner app or browser.
  5. After completing the steps on the partner app or site, the partner service sends the Sonos app the user's credentials as an auth token via a getDeviceAuthToken response.
  6. The partner service redirects the user back to the Sonos app and displays that the music service was successfully added.
  7. (Optional) The partner service opts to refresh the user credentials via:
    1. Automatic token refresh
    2. Manual reauthorization


Differences between authentication methods

Though similar, the two authentication processes have some key differences.

Refer to their respective pages for a more thorough walkthrough:

Anonymous access

You can decide not to use any authentication, also known as anonymous access.

This access type limits the features available for your service. For example, your service could use anonymous access to offer a limited free trial. You can't offer personalization options saved to a user's account, like favorites or playlists. You also can't secure your content from anyone with access to the URL for the media.