Hydro Quickstart Guide

Follow the guide below to learn the Hydro APIs and build your first application

Hydro Overview


Hydro is an open source blockchain protocol incubated by Hydrogen. The Hydrogen 2FA Security App is built on Hydro Raindrop, which provides security through blockchain-based authentication. It offers a server-side authentication protocol for databases, APIs, and large systems, as well as a client-side multi-factor authentication protocol for individual user accounts. Hydro is built on REST principles, with resource oriented URLs and HTTP response codes. All API responses are returned in JSON format.

Sandbox Base URL:https://sandbox.hydrogenplatform.com/hydro/v1
Production Base URL:https://api.hydrogenplatform.com/hydro/v1

Hydro Raindrop

Raindrop is Hydro's security protocol. Raindrop consists of two implementations: Server-side and Client-side. These implementations may be used in conjunction, or independently, according to a company's needs. For instance, a company may use Server-side Raindrop to secure its private databases, while using Client-side Raindrop for users to secure their accounts.


Server-side Raindrop is meant to secure access to large systems, databases, and APIs. Server-side Raindrop consists of a transaction performed via a smart contract that publicly validates access to a private system. The technology complements existing private authentication methods, and is intended to provide additional security for sensitive financial data that is increasingly at risk from hacking and breaches.


Client-side Raindrop is a multi-factor authentication (MFA) solution for client login portals with many end-users frequently requesting access to their respective accounts. Client-side Raindrop integrates through our API with the Hydro app on a user's mobile device to provide an added layer of security on login attempts and other access requests. From the perspective of an end-user, connectivity to the Hydro API for Client-side Raindrop is handled by our mobile app. Accordingly, this guide will focus on helping partners integrate Client-side Raindrop into their applications. While we anticipate that authentication will mainly be used for login portals, Client-side Raindrop authentication can be triggered upon any sensitive financial transaction or event.


Now that we understand the basic of Hydro Raindrop, the first step is to properly authenticate our application. All Hydrogen APIs use OAuth 2.0 to facilitate authorization on the API, an industry standard framework for authorization. Please follow the Authentication Guide in the Hydrogen Atom Quickstart.


There are multiple ways to implement Hydro Raindrop after getting approved as a developer. You can use one of the handy Raindrop plugins available on popular CMS platforms or build a custom implementation!


Hydro Raindrop has pre-configured plugins at the most popular CMS platforms, bringing the power of multi-factor authentication to tens of millions of CMS sites globally. These plugins have a beautiful UI and near instant installation, and are of course 100% free. Please follow the links below to the integrations page which will have instructions for installation:

  • Wordpress
  • Joomla
  • Drupal

  • Custom Implementation

    The examples and screenshots below are drawn from the Raindrop UI example, available on Github. The demo in turn relies on the Raindrop SDK to interface with the Hydro API.

    1. First Time Signup:

    When users of your service elect to enable Client Raindrop, this preference must be associated with their account via the unique identifier specific to your website.

    In the example, users are identified by "Internal Username". For demonstration purposes this field is editable, but in reality you would glean it from an access token, session data, etc. This internal username, which uniquely identifies users in a backend database, should be associated with a flag indicating whether or not the user has opted in to Client Raindrop. In the example, this information is relayed to the frontend and displayed to the user.

    When opting in, users must provide their HydroID. This is a unique identifier assigned to each user in their Hydro mobile app. Before storing the user's HydroID, you'll need to register the user with your application via the Hydro API. Since calling the Hydro API requires secret credentials, the frontend cannot make this call. The Link button in the demo passes the given HydroID to the backend via an internal API which in turn calls the registerUser function of the Raindrop SDK. Ultimately, this function wraps a POST to the /application/client endpoint of the Hydro API.

    After successfully registering the user with the Hydro API, you can then store the association between their Internal Username and their HydroID. In the example, the backend database which stores this information is displayed in the frontend (for demonstration purposes only, to clearly demonstrate the sign-up flow).

    The status of their link may be displayed to users, and an Unregister button should be provided. This button again passes information to the backend, which calls DELETE on the /application/client endpoint via the SDK.

    2. First-Time Verification

    After a successful link, your site must prompt users to verify a signature to confirm their ownership of the HydroID they entered. This ensures that users passed the correct HydroID to your website. This is similar to SMS verification where you would need to send a text to the phone and ask the user to confirm before considering the mapping of internal username to phone number permanent.

    The demo uses the SDK to generate a random 6-digit number that users must enter into their Hydro Mobile App. Note that this code should be generated/validated by the backend, since allowing users to manipulate the code from the frontend could be a security risk. After users successfully enter this number and press Authenticate on your website, they have completed the sign-up process!

    After the verification is complete, the database should be updated accordingly to indicate that the link is confirmed. This is how your website knows which users should be redirected to the permanent verification screen for all future attempts. A basic demonstration of this redirect logic is shown in the example.

    3. Ongoing Verifications

    After users have confirmed that they own their HydroID, they should be redirected to a screen like the one in the example on all login attempts, payment requests, transactions, etc. In practice, your website is free to implement IP-based TTL, account recovery options, or other custom logic on top of this flow.


    After integration, have your users download the Hydro 2FA app on iOS or Android and get instant security and protection against fraud!

    Mobile App

    This video demo shows the mobile app experience for an end user.


    This video demo is an example of the full mobile experience side-by-side with a website. The Hydrogen developer portal, protected by Hydro Raindrop, is used in this example: