Wavebox Security

Wavebox Security

Here at Wavebox we take your security and privacy very seriously.

Everywhere we can we use industry standard tools and supported authentication methods to provide a secure service. I'd like to share with you how some account access is granted to the Wavebox client, so that it can show notifications, unread counts and other stuff.

Wavebox like many other web tools and apps uses a process called OAuth2 to authenticate itself with providers and gain permission to access data on your behalf.

All about OAuth2

OAuth is a protocol that allows Wavebox to gain access to parts of your account with your permission. This is done without the need for Wavebox to store or remember your username and password.

When you start the the OAuth process, Wavebox directs you to the webpage of the service we want to authenticate against (e.g. Google or Microsoft). At this point you are able to sign-in to your account using your web browser as you normally would. Once logged-in, the service will typically present you with a permission screen to give Wavebox access to certain items. By granting access to these services, the Wavebox client receives a secret token which allows it to request allowed information on your behalf.

This dance, with the result of the secret token, allows us to provide you with things like notifications and unread counts. The key benefits of using something like OAuth2 are that:

  • Wavebox doesn’t need to remember your username and password anywhere.
  • The secret token that's generated only has access to certain parts of your account, so for example the Wavebox client can’t change your username or send e-mails as you.
  • The token and access that the Wavebox client has to your account, can be revoked at any time. Most providers give you tools to do this on your account page.


As mentioned above, Wavebox is granted a number of permissions. These differ between services, and it only asks for the permissions it needs. For example, if Wavebox is providing you with notifications and unread counts, you can typically expect it to request something like the following…

  • Some information about you- this would be used to display your account icon in the sidebar as well your email address or username in the app to help you identify your account when using Wavebox.
  • Access some information about your messages - this would be used to find out how many unread messages you have and when you have new ones.

...some of the permissions can sound a little scary, but access to these is only from the Wavebox client on your machine. We don’t share the secret access token with anyone else or even ourselves! Wavebox is open-source, so you can check out the code on Github at anytime and see what’s going on.

Does Wavebox ever use a server-side component?

Some service providers give better tools to third parties like Wavebox, who use a server that is always online. One key example of this is Google. When trying to figure out if there are new emails or notifications available, there are generally 2 widely used methods with both support by Google:

  1. Ask Google for all the latest unread emails you have every few minutes. This is known as polling and works in a similar way to a child in a car asking “Are we there yet” for a 1,000 mile journey! The downside of this, is that notifications often lag a few minutes behind as unread counts are slow to update.

  2. Ask Google to tell Wavebox when you have new emails. This is known as push and works in a similar way to how your sat-nav announces “You’ve arrived at your destination”. Push is widely used amongst mobile apps, with more and more desktop apps and even web apps using it. The key advantage here is that Wavebox knows immediately that you've got something new and everyone in the car knows you’ve arrived without asking.

We’ve been very careful to ensure that access to your data stays with you and not with us. When adding your Google account to Wavebox, you go through two permission screens. The first permission screen identifies you with the Wavebox server; the only access it has is to know who you are. The second permission screen is the 'all-singing-dancing' screen that grants the Wavebox client access to show you notifications etc.

When you open the Wavebox client, it instructs the server to ask Google for updates. It is able to do this because the Wavebox server knows who you are from the authentication step. When your emails change and action needs to be taken, Google tells the Wavebox server exactly that… “something has changed”. We don't know what has changed, not even when it changed, or how it changed - that’s all up to the Wavebox client....we just know that "something" has changed.

It’s important to highlight this point. The server does not receive any of the actual changes because it doesn’t have access to this data. Imagine the Wavebox server like a pager or bleeper from the 90's. It passes the "something has changed" message to the client on your machine. At this point the client calls up Google and it will then find out from if there’s a notification to be shown or unread count to update.

This process is quite complex and a little involved. However if you’d like to know more about how all this works the developer documentation from Google is freely available online and if you want to see how it all ties together check out the code that Wavebox uses on Github.

Phew! A bit of a techie blog post, but hopefully you were able to follow along! Wavebox was built from the ground-up with your privacy in mind. We keep access to your stuff with you and only request access to things we need. If you feel like there are any other parts of this post that need more explanation or go a bit too techie then please do get in touch, we’d love to improve it!