Logos for Hypothesis and OAuth.We’ve recently released a set of changes to make a dramatic shift in how Hypothesis handles authentication. Most users won’t notice a difference, but now Hypothesis uses the standard OAuth authentication protocol, which makes logging in more secure and easier across a wider range of browsers and devices.

Looking ahead, OAuth also lays a foundation for two new authentication pathways: Social login, for users who want to annotate using their existing personal identities from services like Facebook, Google, ORCID, Microsoft, or Twitter. And integration with organizational identity services, a widespread need for websites, publishers and platforms that want to enable annotation for their users without asking them to create separate, additional Hypothesis accounts.

Our new OAuth-based authentication replaces a cookie-based system, addressing recurring login issues experienced by some Hypothesis users. Now login is enabled for users whose browsers block “third-party” cookies in order to prevent advertisers from tracking them across the web or who use privacy extensions like Privacy Badger, which also block the use of third-party cookies on sites a user hasn’t visited. These users should no longer see those pesky “session is invalid” errors that block their authentication.


Screenshot of Hypothesis error: session is invalid.


Another issue the move to OAuth addresses is that some Hypothesis capabilities (eg, joining or leaving groups) have only been available through our official clients using cookie-based authentication requests, but now can be available in third-party clients that use token-authenticated requests.

Additionally, because we no longer use cookie-based authentication, we no longer need to ask for permissions that the Hypothesis application doesn’t really need in order to run correctly. So users will no longer be asked to grant unneeded permissions for geolocation, or camera or microphone access.

What we’ve built

We have implemented OAuth in the Hypothesis service, and made our official clients (the sidebar and browser extensions) use OAuth to obtain credentials (access tokens) for making API requests. We have also provided public OAuth API methods in the service to replace undocumented cookie-authenticated endpoints.

From a user’s point of view, little has changed. We have moved login using username and password out of the sidebar and into a popup window, which can be used not only by official Hypothesis clients but also by registered third-party clients.

Try it yourself

Open the Hypothesis sidebar on any page and make sure you’re logged out from the user menu at the upper right.


Screenshot of logging out of Hypothesis.


Then log in again using the link at the upper right and enter your username and password in the pop up window. If you’ve already logged in using OAuth, the popup window may just quickly appear and disappear as it uses an access token you’ve already established.


Screenshot of logging in to Hypothesis.