Put Some Music On: Your First Sonos Platform Calls with Postman

The Sonos Control API has been used to build some really great experiences. These range from big and ambitious, to smaller and more straightforward. But what if you want to start smaller still? What if you just want to dip your toe in, and get a feel for how things fit together? We’ll find out one way to do that in this post.

Postman is a configurable REST client, used to test and experiment with APIs. We’ll use it to set up authentication, and build some Control API calls. Let’s forget the UX and presentation and everything else associated with a full-fledged app. We’re going to focus on nothing but getting the music playing.

If you’re the type that likes to read the last page of a good book, scroll to the bottom, where I’ve included all the work done here in a pre-packaged project for you to use. But you should still read the rest of the post!

Getting Started

First, let’s collect our materials:

  • A set-up and configured Sonos system, obviously. Make sure you can play some content on it.
  • The username and password associated with that Sonos system.
  • A few Sonos Favorites saved and showing up in My Sonos.
  • A Control Integration, complete with a Client Key and Secret.
  • An installed copy of Postman, the REST client.
  • Some good hacking music. I’d suggest something by Matthew E. White.

Fire up Postman and look around. We’ll build the required Environment and Collection to generate Sonos API calls.

Set Up the Environment

Before we get started on actual API calls, we need to set up an Environment for our collection to use. An environment, in Postman, is a collection of variables that any collection has access to. So, for instance, you can use {{auth_url}} instead of api.sonos.com. This lets you use the variable in multiple places, and only change the variable value in the environment definition if that value ever needs to change.

Let’s get our Environment set up. Click on the “Manage Environments” button in the upper right of the Postman window. It looks like a gear icon. Then, click on the big, orange “Add” button. Fill it out such that it looks like this:


Let’s go over each of the environment variables we’ve specified.

auth_host – The host that handles Sonos authorization calls.
api_host – The host that handles Sonos Control API calls.
client_key – The client key provided when you create a new Control Integration.
client_secret – The client secret provided when you create a new Control integration.

Once you’ve gotten everything set up as noted above, click on “Update”, then close the Environment window. We’re ready to start actually making calls.


The next thing we’re going to want to do is create a new collection. A Postman collection is, well, a collection of related REST calls that can share resources. In our case, we’re going to build the authorization handling right in this collection. We’ll let the REST calls contained inside the collection use this authorization so we don’t have to reconfigure for every call.

Click the “New Collection” button in the left column of the Postman window.


Give your collection a name, and a description of you’d like.


Click on the “Authorization” tab. This is where we do the first really meaty, interesting part. Before we go any further, it’s a good idea to read over the Authorize section of our documentation. That’ll explain the details behind what we’re doing here, and will help make things more clear when you’re building an actual implementation and don’t simply have form fields to fill in.

On the “Authorization” window, select “OAuth 2.0” for the type, and “Request Header” for “Add auth data to”. As noted in our documentation, we employ a standard OAuth 2.0 3-legged OAuth flow, and require that the acquired token is included in request headers.


Now we’re going to click on the big orange “Get New Access Token” button on the right side of the window. Here, we’ll fill in the information required to actually get an access token. Fill in everything, so that it looks like this:


You’ll note a bunch of orange values, surrounded by double curly brackets. Those are the Postman environment variables, which you set up in the previous section.

Let’s run through these fields, one at a time.

Token Name – You can use whatever you want. This is just so that you can remember the token you fetched. I just leave it at the default
Grant Type – Sonos employs an Authorization Code flow, so you should select that here.
Callback URL – This is the URL that is called when the Sonos auth servers want to send the user back to your integration. This callback URL should be prepared to receive data involved in the auth flow, as described in our Authorization docs. This Callback Url must match the redirect uri you specified when you created your Control Integration on the developer portal. The “http://localhost” value included in this screenshot is for my specific integration, and should be changed to match your setup. Note that, while Postman calls it a Callback URL, it is more commonly referred to as a redirect uri. Sonos uses this name, and in fact has a separate, unrelated Control Integration parameter called “Callback URL” which is for player eventing.
Auth URL – This is the URL that an integration will call to get the initial Authorization Code
Access Token URL – An integration will call this URL, with the authorization code, to get access and refresh tokens.
Client ID – The client ID that was generated for you when you created your Control integration.
Client Secret – The client secret that was generated for you when you created your Control integration
Scope – The types of abilities your integration is requesting on behalf of the user. At the time of this writing, the only available scope for Sonos is “playback-control-all”.
State – A value built in the OAuth spec that is used to prevent cross-site forgeries. The {{$guid}} value in the screenshot is a random value generator (more or less) provided by Postman.

Once this is all filled out, click on the big orange “Request Token” button. This will initiate an actual OAuth flow against the Sonos servers, exactly as a user would see inside an actual integration. You’ll be directed to the Sonos login page, told a bit about how to prepare your Sonos system to integrate with third parties, and then be prompted for your username and password.


Once you’ve successfully supplied your credentials, you’ll be told about the capabilities the integration is asking for. These are defined by the “scope” parameter in your Authorization calls.


Once you click “OK” here, the user is sent back to the redirect/callback URI specified above. Normally, your hypothetical integration would take over at this point, getting the authorization code, then exchanging it for the access token. In this case, though, Postman scrapes the redirect call, gathers the required data, and completes the OAuth flow itself, eventually presenting you with a token that you can choose to use.

Congratulations! You’ve successfully authenticated against the Sonos platform!

Making Your First Call

Now that Postman has the authentication information the Sonos requires for any API call, we can start building those calls. Before we can get to the really fun stuff, like music playback, we have to understand a bit about the user’s system. The user, in this case, is whoever logged in to the Sonos authorization page in the section above. We’ll want to get a list of available households first. Usually, there will be only a single household per user, but it’s quite possible for a user to have more than one. In either case, we need to get a householdId to use to make further calls. You can read a more high level description of this flow in the “Discover” section of our documentation.

Click on the ellipsis (“…”) button on the bottom right of your collection in Postman, then select “Add Folder”. I like to create folders for each namespace in the Sonos API, so I’ll call this one “households”. On the description tab, enter “households” as the Name.

Next select the Authorization tab. This is where Postman really comes in handy. Instead of rebuilding our authorization flow from scratch, we’ll simply select “Inherit Auth from parent” for the type.

Click the orange “Create” button to create the folder and to close this window. Now, let’s add our first request. Click the ellipsis button on the “households” folder. Sometimes you need to hover the mouse over the folder name for this menu to appear. Then, click the “Add Request” menu item. Let’s call this one “households”, since we’ll be doing a simple GET /households request.

You’ll notice that when you save it, it is conveniently labeled right inside the parent folder, with the http method (GET, in this case) helping us identify it. Select the request in the column on the left, and notice that request details page that becomes visible. This is where we’ll specify the command endpoint, as well as any body elements that are required. Fill out the request details as noted below

Notice again that we’re using environment variables, this time {{api_host}}, to build our request. Note also that we’ve once again specified that the request should inherit its auth from its parent. Auth flow from the top level collection is being passed down to the “households” folder, then down to this GET /households request.

For a simple GET /households request, this is all that’s required, so let’s make our very first call! Click on the big blue “Send” button. You should get back a JSON body that looks something like this:

There you go! You’ve got your list of Sonos households available to the authenticated user. Note the household id returned above, as we’ll need that for the next section. If you’ve got more than one household available, just pick one of the ids returned.

Finding Out What Groups and Players are Available

Most commands on the Sonos Control API require either the householdId or the targeted groupId. We’ve got the hhid, so let’s make a call and get a target groupId. We’ll build a GET /groups request to return what we’re looking for. Just as above, we’ll make a new folder, this time for the “groups” namespace, and then a new request inside that new folder for the actual GET /groups call. To summarize:

  1. Create a new “groups” folder.
  2. Create a new “groups” command.
  3. Set the auth type to “inherit”, and enter the URL as such: https://{{api_host}}/control/api/v1/households/<< householdId from above >>/groups

If you click “Send” now, you should get back a groups response object that contains all of the players in the household, as well as a listing of how those players are currently grouped. It’ll look something like this

Just like before, we’re going to want to grab a groupId from one of these, so pick a group that looks interesting from the groups object in the response. Note the associated groupId. In the example above, there are two groups returned, so I might choose the “Office Speakers + 1” group, with the RINCON_11111:12345 id.

Get the Sonos Favorites

So we’ve gotten all the boring housekeeping out of the way; now it’s time to actually make our Sonos speakers do something. Let’s put a Sonos Favorite on the group you just selected. If you haven’t done so yet, make sure you’ve added something to “My Sonos”, which is the Sonos app container for favorites and playlists. We’ll use the favorites namespace to look for saved favorites, then play one back.

The first thing we’ll want to do is execute a GET /favorites command. You know the drill at this point:

  1. Create a new “favorites” folder underneath the top level collection.
  2. Create a new “favorite” command.
  3. Set the auth type to “inherit”, and enter the URL as such: https://{{api_host}}/control/api/v1/households/<< householdId from above >>/favorites

That’s it. If you hit “Send” now, you should get back a JSON body containing all of the Sonos Favorites you’ve saved. It should look something like this:

Pick your favorite Favorite, and note the id. We’ll be using that in the next section.

Finally, Let’s Play Some Music

We’ve gotten the household id. We’ve used that to get the list of available groups, and then picked a group id. We’ve gotten a favorite id. Not let’s put it all together and play that favorite on that group.

Inside the existing “favorites” folder, let’s create a new request, and call it “loadFavorites”. Have it inherit its parent’s auth, of course. But here’s where things get a little different. The first thing we’ll do is change the HTTP method from the default GET to POST. This means we’re sending data to the request endpoint instead of just asking for data. Check out the following screenshot of how you should get things configured.

You’ll note that this time, we’ve included a request body by clicking on the “Body” tab in the request. The JSON in that body tells Sonos which favorite id to play, and how to queue it up. Obviously, if the favorite you’ve selected is a streaming radio station, setting the play mode shuffle to TRUE doesn’t make any sense, and is ignored.

Hitting “Send” on this request should result in your selected Sonos Favorite playing on your selected Sonos group. Congratulations! You’ve built your first Sonos app. Of course, there’s no UX around it, and you’re doing all the heavy lifting instead of letting code do it, but make no mistake, this is an integration.

Wrap Up

We’ve learned here how to use Postman to authenticate against Sonos’ servers, and how to make requests to find out about the state of a user’s system. And finally, we actually made music play. From here, some great next steps would be to implement more commands, like volume or playback control, inside Postman. Get a feel for how things fit together.

A couple notes:

  1. Obviously, you can’t subscribe to any eventing with Postman.
  2. For whatever reason, Postman doesn’t implement support for refresh tokens, so you’ll have to go back in to the top collection’s Authorization screen and request a new token every 24 hours.

And finally, here’s a special treat. Clicking this button will import a new Postman Collection and Environment, all set up with a number of Sonos namespaces. In addition, I’ve created a number of post-request scripts that will parse the results, and do things like automatically populate groupIds into calls. All you need to do is open the enclosed Environment and set “target_player” to the name of a player in your household, and add your client key and secret. After that, every time you run the GET /groups command, Postman will look for your player in the response, find its current group, and use that groupId in other requests, like loadFavorite.

Thanks for reading, and we’re so excited that you’re building great things with us.

Meet Your Sonos Sound Platform Dev Advocates

Welcome to the Sonos Sound Platform. We’d like to take a couple minutes of your time to introduce ourselves. We’re the developer advocates for the Sonos platform, and we can’t wait to help you build incredible experiences for our listeners.


I’m Matt Welch, and I’m the lead dev advocate for the platform. My sole goal is to help devs and partners build incredible things on our platform. I’ve been a Sonos owner for about 8 years, and was actually hacking on Sonos before I even joined the company. I wrote a lot of blog posts on the subject in that unofficial capacity. I’m looking forward to writing a lot of posts here in my more official capacity.

Currently listening to: Great Thunder, the latest Waxahatchee record
First Concert: Adam Ant at the Norfolk Boathouse


I’m Nancy Hernandez, a developer advocate here to support you through your journey on the Platform. I’ve been at Sonos for over 4 years now and enjoying every minute. Look forward to connecting with you through this blog.

Currently listening to: Rock This
First Concert: Wango Tango at the Rose Bowl

Of course, we’re just the public representatives of the platform. There’s a big team that has built this platform over the past few years. We are deeply grateful to and proud of them. We’ll be introducing them to you all on this blog as we grow the platform together.

Welcome. Let’s Build Great Things

We won’t keep you any more, as we know you’re anxious to start making things. Dig in to our docs, read about everything you can do, and build great experiences for our listeners. We’ll leave you with a playlist of tunes, selected by the men and women who built the Sonos Sound Platform. This was the fuel that drove our team as we put this all together. We hope it helps you make great things.

Introducing the Sonos Sound Platform: Building the Future of the Sonic Internet

We’re opening up our developer platform and APIs to make it easier than ever to partner with Sonos and build new sound experiences for the home.

To most, we make speakers. But when you think about the unique experience you have with Sonos, it owes just as much to the magic of the underlying software as it does to hardware. It’s through our platform that, together with partners, we can bring new experiences to listeners, ultimately providing unparalleled freedom of choice across music services, audiobooks, television and video content, podcasts, voice service and home automation.

When Sonos first got started 16 years ago, the technology landscape looked very different. For one thing, on-demand streaming music services didn’t even exist. Fast forward to today and the pace of innovation has been profound; the rise of streaming media, cloud computing, artificial intelligence and Internet of Things (IoT) technology are now pervasive, allowing developers to rapidly bring innovation to market.

Today, we begin the next chapter of partnering at Sonos by introducing the Sonos sound platform, which brings together new APIs, developer tools and documentation. In launching the new platform, we have three specific objectives in mind.

  1. Create new opportunities for our partners

    • Three trends are transforming the home audio market: the rise in paid streaming, rise of voice assistant speakers and the rise of the smart home. The Sonos sound platform will be the gateway through which partners can harness this growth with their own innovative solutions.
    • New cloud APIs allow us to deliver advanced capabilities for partners to build upon. Similarly, enhanced LAN-based APIs support solutions that demand low latency or the local network.
    • We will introduce capabilities to the sound platform on a regular cadence so that our joint-customers continue to get new experiences over time. We will listen carefully to our partner community and customers to make sure we are prioritizing the right investments.
  2. Making the platform more approachable for developers

    • The sound platform’s modernized APIs allow more developers than ever to bring their solutions to market. We will also invest in samples, SDKs and libraries to make it easier and faster for developers to build against the new platform.
    • Our new developer portal (https://developer.sonos.com), provides one place to create, configure and monitor integrations. Our developer advocates will be active in the community on Stack Overflow and GitHub so developers can get support with development. This blog will serve as one place to learn about new platform innovations as well as technical posts from developer advocates and product team members at Sonos.
    • Finally, our documentation has been written from the ground up with comprehensive content for developers of all experience levels, with getting started guides and technical reference docs. In addition, our Sound Experience Guidelines capture the essence of the Sonos “experience”, helping developers craft solutions that delight the user.
  3. Provide customers more personalized experiences and confidence through certification

    • We are working to add intelligence to the sound platform so customers can enjoy more natural and personal experiences on Sonos and will enable our partners to complement with their own smarts, over time.
    • The “Works with Sonos” badge allows customers to confidently identify partner solutions that work seamlessly with the Sonos system. We will continue to invest in ways for customers to more easily discover and engage with partner solutions. More details on the Works with Sonos program will be shared in a future blog post.
    • Finally, in addition to new capabilities, we will continue to invest in the reliability and security of our platform to ensure customers receive predictable experiences they expect from Sonos and our partner integrations.

With today’s launch, we are releasing a set of new control APIs that allow developers to observe and control Sonos players. Coming later this year in October, we will be following up with additional capabilities:

  • Notifications/Audio Clips – Play short, discrete sounds and notifications on a player without fully interrupting the music. The song or audio will lower in volume and resume following the notification.
  • Sonos Playlists – The ability to list and start playback of Sonos Playlists within a third-party interface.
  • Max Volume and Volume Pass-through – Partner integrations will be able to set the maximum volume of Sonos players, as well as subscribe to volume events for fixed-volume players. This will allow, for example, an A/V receiver to have its volume controlled via the Sonos app when connected to a Sonos Connect.

Thank you for your ongoing partnership as we help the world listen better, together.

James Senior
Director of Product, Platform & Partnerships, Sonos